The uTorrent Web WebUI API allows developers to programmatically control the uTorrent client over HTTP. This guide covers authentication, essential endpoints, and automation scripts to help you integrate uTorrent into your development workflow. Understanding the WebUI Architecture
The uTorrent API operates as a self-hosted HTTP server inside the desktop application. It communicates via standard GET and POST requests, returning data in structured JSON format.
Before sending commands, you must enable the WebUI interface in your client settings: Navigate to Options > Preferences > Advanced > WebUI. Check the box to Enable WebUI. Set a unique Username and Password.
Restrict access to a specific Alternative listening port (default is usually 8080). The Two-Step Authentication Process
Security in the uTorrent API relies on HTTP Basic Authentication combined with a mandatory token system to prevent Cross-Site Request Forgery (CSRF) attacks. Every session requires fetching a token before executing any commands. 1. Fetching the Token
Send a GET request to the token endpoint using HTTP Basic Authentication.
GET http://localhost:8080/gui/token.html Authorization: Basic [Base64 Encoded username:password] Use code with caution.
The server returns an HTML response containing the token inside a
Use code with caution. 2. Making Authorized Requests
For all subsequent API calls, append the token as a query parameter (&token=YOUR_TOKEN) and include your authentication headers. Core API Endpoints and Actions
All API actions target the base URL http://localhost:8080/gui/ and use query parameters to specify actions. Retrieve the Torrent List
To get the status, progress, and metadata of all current torrents, use the list=1 parameter. GET http://localhost:8080/gui/?list=1&token=YOUR_TOKEN Use code with caution. Control Torrent States
Manage individual torrent jobs by targeting them with their unique Info-Hash (hash). Start: ?action=start&hash=TORRENT_HASH Stop: ?action=stop&hash=TORRENT_HASH Pause: ?action=pause&hash=TORRENT_HASH Force Start: ?action=forcestart&hash=TORRENT_HASH Remove: ?action=remove&hash=TORRENT_HASH Remove Data: ?action=removedata&hash=TORRENT_HASH Add Torrents Remotely
You can add downloads via a web URL, a magnet link, or by uploading a local .torrent file. Via URL/Magnet:
GET http://localhost:8080/gui/?action=add-url&s=MAGNET_OR_URL&token=YOUR_TOKEN Use code with caution.
Via File Upload:Send a POST request with multipart/form-data encoding to ?action=add-file. Automation Script: Python Implementation
The following Python script automates the process of authenticating, retrieving the token, and adding a new magnet link to your queue.
import requests import re from requests.auth import HTTPBasicAuth # Configuration BASE_URL = “http://localhost:8080/gui/” USERNAME = “your_username” PASSWORD = “your_password” MAGNET_LINK = “magnet:?xt=urn:btih:…” # Initialize session to persist cookies session = requests.Session() session.auth = HTTPBasicAuth(USERNAME, PASSWORD) try: # Step 1: Request Token token_url = f”{BASE_URL}token.html” response = session.get(token_url) response.raise_for_status() # Extract token using Regex match = re.search(r”
”, response.text) if not match: raise ValueError(“Token not found in response.”) token = match.group(1) print(f”Successfully authenticated. Token: {token[:10]}…“) # Step 2: Add Torrent add_url = f”{BASE_URL}?action=add-url&s={MAGNET_LINK}&token={token}” add_response = session.get(add_url) add_response.raise_for_status() print(“Success: Torrent added to uTorrent queue.”) except requests.exceptions.RequestException as e: print(f”API Connection Error: {e}“) except Exception as e: print(f”Error: {e}“) Use code with caution. Best Practices for Production Automation
Token Caching: Do not request a new token for every individual action. Store the token and reuse it alongside the session cookie until it expires or errors out.
Rate Limiting: Implement brief delays (e.g., 500ms) between consecutive aggressive API calls to prevent the local uTorrent process from locking up or dropping connections.
Error Handling: Always handle HTTP 401 Unauthorized errors (signaling credential issues) and 400 Bad Request errors (signaling an expired token or missing cookie).
If you want to build out a specific automation feature, tell me: What programming language do you prefer?
What trigger event should start a download (e.g., RSS feed, folder watch, Webhook)? I can provide targeted code to complete your integration.
Leave a Reply