aria2
EN
Guide · aria2 1.37.0

aria2 JSON-RPC: control aria2 from anything

With RPC turned on, aria2 becomes a download server that WebUIs, browser extensions, phone apps and your own scripts can drive. This guide covers every method, with responses recorded from a running aria2 1.37.0.

Last updated: Tested with aria2 1.37.0

Start in two commands

Start aria2 with RPC and a secret, then send it a request. Any tool that can make an HTTP POST works; here it is curl.

aria2c --enable-rpc --rpc-secret=s3cretcurl -s http://localhost:6800/jsonrpc -d '{"jsonrpc":"2.0","id":"1","method":"aria2.getVersion","params":["token:s3cret"]}'{"id":"1","jsonrpc":"2.0","result":{"enabledFeatures":["Async DNS","BitTorrent","Firefox3 Cookie","GZip","HTTPS","Message Digest","Metalink","XML-RPC","SFTP"],"version":"1.37.0"}}

aria2 now listens on port 6800 on this computer only. Add --rpc-listen-all=true only when another device on a trusted network must connect, and --rpc-allow-origin-all=true when a web page in a browser calls it.

Test your connection

Check from this page whether your browser can reach your aria2. It sends aria2.getVersion to the address you enter, and nothing else.

What a call looks like

Every request is a small JSON object. These are its parts:

  1. "jsonrpc": "2.0"Always this value.
  2. "id": "1"Any string you choose. aria2 copies it into the reply, so you can match replies to requests.
  3. "method": "aria2.addUri"One of the 36 methods below.
  4. "token:s3cret"The first parameter: your --rpc-secret, prefixed with token:. Every aria2.* method needs it.
  5. ["https://…"]The method's own parameters follow, in order.
  6. {"split": "16"}Options use the names from the options reference, and their values are strings.

Five ways to send it

All five were tested against aria2 1.37.0.

01

HTTP POST to /jsonrpc

The usual way. The body is the JSON request.

02

WebSocket at ws://host:6800/jsonrpc

Same requests over a persistent connection, plus notifications pushed by aria2. Use wss:// with --rpc-secure.

03

A batch: a JSON array of requests

aria2 answers with an array of replies, in the same order.

04

system.multicall

One request that runs several methods. Each inner call carries its own token; the outer one has none.

05

XML-RPC at /rpc

The same methods for XML-RPC clients. Values are XML-RPC types instead of JSON.

All 36 methods

Parameters are listed after the token. Open a row to see a real request and aria2's real reply.

Add downloads

aria2.addUri (uris[], options?, position?) → GID Adds a download from one or more URLs of the same file (HTTP, FTP, SFTP, magnet).

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "3",
 "method": "aria2.addUri",
 "params": [
  "token:s3cret",
  [
   "https://example.com/file.iso"
  ],
  {
   "max-download-limit": "2M",
   "out": "big.bin"
  }
 ]
}
{
 "id": "3",
 "jsonrpc": "2.0",
 "result": "35b6f22ff341c545"
}
aria2.addTorrent (torrent (base64), uris[]?, options?, position?) → GID Adds a torrent from the contents of a .torrent file, base64-encoded.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "14",
 "method": "aria2.addTorrent",
 "params": [
  "token:s3cret",
  "ZDg6YW5ub3VuY2UzMDpodHRwOi8vMTI3LjAuMC4xOjY5NjkvYW5ub3VuY2U0OmluZm9kNTpmaWxlc2xkNjpsZW5ndGhpMzAwMDAwZTQ6cGF0aGw5OnZpZGVvLm1rdmVlZDY6bGVuZ3RoaTEwMDBlNDpwYXRobDM6c3ViMTA6cmVhZG1lLnR4dGVlZDY6bGVuZ3RoaTcwMDAwZTQ6cGF0aGwzOnN1Yjk6Y292ZXIuanBnZWVlNDpuYW1lNDpkYXRhMTI6cGllY2UgbGVuZ3RoaTMyNzY4ZTY6cGllY2VzMjQwOpnUbKtB9UspPRSPmbRPBUyJ4y39+NKrYmMRZk3KJrBmwmb9ZgFD/ZbZAb/DTO3/tg0h3x15maLsKqRFgLJpURN/kvfmhAWGoDcxtJNbmObQVfZxkDNIllU5fFojZ4o+5uv8vJlpbXjZnKhXPU48QpPdWyYe/OWnK5yA+SAPzBxkDz2CLRTSXfcu0wS/E1wLRr0NNc+2E0OosvKm+/l7lQ1o8fcZ14G+RSDCDg7B5C3ASfCf/KaLkPktmBHzIxjjbjDMSJH8cQ7FcnC6dXVbB0zbe0FxnaHias8yNDiO+gnEKsbmDx8dafwjjUeU1vLBiWVl",
  [],
  {
   "pause": "true"
  }
 ]
}
{
 "id": "14",
 "jsonrpc": "2.0",
 "result": "7e95de64eed32e26"
}

Pause, resume, remove

aria2.remove (gid) → GID Stops and removes a download, after telling trackers and closing connections.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "26",
 "method": "aria2.remove",
 "params": [
  "token:s3cret",
  "7e95de64eed32e26"
 ]
}
{
 "id": "26",
 "jsonrpc": "2.0",
 "result": "7e95de64eed32e26"
}
aria2.forceRemove (gid) → GID Removes a download at once, without the clean-up steps.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "31",
 "method": "aria2.forceRemove",
 "params": [
  "token:s3cret",
  "35b6f22ff341c545"
 ]
}
{
 "id": "31",
 "jsonrpc": "2.0",
 "result": "35b6f22ff341c545"
}
aria2.pause (gid) → GID Pauses a download. It stays in the queue until you unpause it.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "10",
 "method": "aria2.pause",
 "params": [
  "token:s3cret",
  "35b6f22ff341c545"
 ]
}
{
 "id": "10",
 "jsonrpc": "2.0",
 "result": "35b6f22ff341c545"
}
aria2.forcePause (gid) → GID Pauses at once, without the clean-up steps.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "27",
 "method": "aria2.forcePause",
 "params": [
  "token:s3cret",
  "35b6f22ff341c545"
 ]
}
{
 "id": "27",
 "jsonrpc": "2.0",
 "result": "35b6f22ff341c545"
}
aria2.pauseAll () → "OK" Pauses every active and waiting download.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "29",
 "method": "aria2.pauseAll",
 "params": [
  "token:s3cret"
 ]
}
{
 "id": "29",
 "jsonrpc": "2.0",
 "result": "OK"
}
aria2.forcePauseAll () → "OK" Pauses everything at once.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "28",
 "method": "aria2.forcePauseAll",
 "params": [
  "token:s3cret"
 ]
}
{
 "id": "28",
 "jsonrpc": "2.0",
 "result": "OK"
}
aria2.unpause (gid) → GID Puts a paused download back in the queue.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "12",
 "method": "aria2.unpause",
 "params": [
  "token:s3cret",
  "35b6f22ff341c545"
 ]
}
{
 "id": "12",
 "jsonrpc": "2.0",
 "result": "35b6f22ff341c545"
}
aria2.unpauseAll () → "OK" Puts every paused download back in the queue.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "30",
 "method": "aria2.unpauseAll",
 "params": [
  "token:s3cret"
 ]
}
{
 "id": "30",
 "jsonrpc": "2.0",
 "result": "OK"
}
aria2.changePosition (gid, pos, POS_SET | POS_CUR | POS_END) → new position Moves a download in the waiting queue: to a position, up or down by a number, or relative to the end.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "16",
 "method": "aria2.changePosition",
 "params": [
  "token:s3cret",
  "7e95de64eed32e26",
  0,
  "POS_SET"
 ]
}
{
 "id": "16",
 "jsonrpc": "2.0",
 "result": 0
}
aria2.changeUri (gid, fileIndex, delUris[], addUris[], position?) → [deleted, added] Removes and adds URLs (mirrors) of one file of a download.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "17",
 "method": "aria2.changeUri",
 "params": [
  "token:s3cret",
  "35b6f22ff341c545",
  1,
  [],
  [
   "https://mirror.example.com/file.iso"
  ]
 ]
}
{
 "id": "17",
 "jsonrpc": "2.0",
 "result": [
  0,
  1
 ]
}

Watch downloads

aria2.tellStatus (gid, keys[]?) → status object Progress and details of one download. Pass a list of keys to get only those.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "4",
 "method": "aria2.tellStatus",
 "params": [
  "token:s3cret",
  "35b6f22ff341c545",
  [
   "gid",
   "status",
   "totalLength",
   "completedLength",
   "downloadSpeed",
   "connections",
   "dir"
  ]
 ]
}
{
 "id": "4",
 "jsonrpc": "2.0",
 "result": {
  "completedLength": "2113536",
  "connections": "1",
  "dir": "/downloads",
  "downloadSpeed": "1467780",
  "gid": "35b6f22ff341c545",
  "status": "active",
  "totalLength": "50000000"
 }
}
aria2.getUris (gid) → URI list The URLs of a download and whether each is used or waiting.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "6",
 "method": "aria2.getUris",
 "params": [
  "token:s3cret",
  "35b6f22ff341c545"
 ]
}
{
 "id": "6",
 "jsonrpc": "2.0",
 "result": [
  {
   "status": "used",
   "uri": "https://example.com/file.iso"
  },
  {
   "status": "waiting",
   "uri": "https://example.com/file.iso"
  }
 ]
}
aria2.getFiles (gid) → file list The files of a download, with size, progress and selection.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "5",
 "method": "aria2.getFiles",
 "params": [
  "token:s3cret",
  "35b6f22ff341c545"
 ]
}
{
 "id": "5",
 "jsonrpc": "2.0",
 "result": [
  {
   "completedLength": "2097152",
   "index": "1",
   "length": "50000000",
   "path": "/downloads/big.bin",
   "selected": "true",
   "uris": [
    {
     "status": "used",
     "uri": "https://example.com/file.iso"
    },
    "…"
   ]
  }
 ]
}
aria2.getPeers (gid) → peer list The BitTorrent peers of a torrent download.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "15",
 "method": "aria2.getPeers",
 "params": [
  "token:s3cret",
  "7e95de64eed32e26"
 ]
}
{
 "id": "15",
 "jsonrpc": "2.0",
 "result": []
}
aria2.getServers (gid) → server list The servers each file is currently downloading from, with their speed.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "7",
 "method": "aria2.getServers",
 "params": [
  "token:s3cret",
  "35b6f22ff341c545"
 ]
}
{
 "id": "7",
 "jsonrpc": "2.0",
 "result": [
  {
   "index": "1",
   "servers": [
    {
     "currentUri": "https://example.com/file.iso",
     "downloadSpeed": "1458725",
     "uri": "https://example.com/file.iso"
    }
   ]
  }
 ]
}
aria2.tellActive (keys[]?) → status objects All downloads that are running now.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "13",
 "method": "aria2.tellActive",
 "params": [
  "token:s3cret",
  [
   "gid",
   "status",
   "downloadSpeed"
  ]
 ]
}
{
 "id": "13",
 "jsonrpc": "2.0",
 "result": [
  {
   "downloadSpeed": "0",
   "gid": "35b6f22ff341c545",
   "status": "active"
  }
 ]
}
aria2.tellWaiting (offset, num, keys[]?) → status objects Waiting and paused downloads, from offset, at most num.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "11",
 "method": "aria2.tellWaiting",
 "params": [
  "token:s3cret",
  0,
  10,
  [
   "gid",
   "status"
  ]
 ]
}
{
 "id": "11",
 "jsonrpc": "2.0",
 "result": [
  {
   "gid": "35b6f22ff341c545",
   "status": "paused"
  }
 ]
}
aria2.tellStopped (offset, num, keys[]?) → status objects Finished, failed and removed downloads still in memory.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "32",
 "method": "aria2.tellStopped",
 "params": [
  "token:s3cret",
  0,
  10,
  [
   "gid",
   "status",
   "errorCode"
  ]
 ]
}
{
 "id": "32",
 "jsonrpc": "2.0",
 "result": [
  {
   "errorCode": "0",
   "gid": "4792fc4fda863437",
   "status": "complete"
  },
  {
   "errorCode": "31",
   "gid": "35b6f22ff341c545",
   "status": "removed"
  }
 ]
}

Change options

aria2.getOption (gid) → options All options of one download.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "9",
 "method": "aria2.getOption",
 "params": [
  "token:s3cret",
  "35b6f22ff341c545"
 ]
}
{
 "id": "9",
 "jsonrpc": "2.0",
 "result": {
  "allow-overwrite": "false",
  "allow-piece-length-change": "false",
  "always-resume": "true",
  "async-dns": "true",
  "…": "…"
 }
}
aria2.changeOption (gid, options) → "OK" Changes options of one download. On a running download only 7 options can change; see the options reference.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "8",
 "method": "aria2.changeOption",
 "params": [
  "token:s3cret",
  "35b6f22ff341c545",
  {
   "max-download-limit": "4M"
  }
 ]
}
{
 "id": "8",
 "jsonrpc": "2.0",
 "result": "OK"
}
aria2.getGlobalOption () → options aria2's current global options.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "18",
 "method": "aria2.getGlobalOption",
 "params": [
  "token:s3cret"
 ]
}
{
 "id": "18",
 "jsonrpc": "2.0",
 "result": {
  "allow-overwrite": "false",
  "allow-piece-length-change": "false",
  "always-resume": "true",
  "async-dns": "true",
  "…": "…"
 }
}
aria2.changeGlobalOption (options) → "OK" Changes global options while aria2 runs, such as the speed limits or max-concurrent-downloads.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "19",
 "method": "aria2.changeGlobalOption",
 "params": [
  "token:s3cret",
  {
   "max-concurrent-downloads": "3"
  }
 ]
}
{
 "id": "19",
 "jsonrpc": "2.0",
 "result": "OK"
}

aria2 itself

aria2.getGlobalStat () → speeds and counts Total download and upload speed and the number of active, waiting and stopped downloads.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "20",
 "method": "aria2.getGlobalStat",
 "params": [
  "token:s3cret"
 ]
}
{
 "id": "20",
 "jsonrpc": "2.0",
 "result": {
  "downloadSpeed": "928974",
  "numActive": "1",
  "numStopped": "0",
  "numStoppedTotal": "0",
  "numWaiting": "1",
  "uploadSpeed": "0"
 }
}
aria2.purgeDownloadResult () → "OK" Forgets all finished, failed and removed downloads.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "34",
 "method": "aria2.purgeDownloadResult",
 "params": [
  "token:s3cret"
 ]
}
{
 "id": "34",
 "jsonrpc": "2.0",
 "result": "OK"
}
aria2.removeDownloadResult (gid) → "OK" Forgets one finished, failed or removed download.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "33",
 "method": "aria2.removeDownloadResult",
 "params": [
  "token:s3cret",
  "35b6f22ff341c545"
 ]
}
{
 "id": "33",
 "jsonrpc": "2.0",
 "result": "OK"
}
aria2.getVersion () → version, features The aria2 version and the features it was built with. A good first call to test a connection.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "1",
 "method": "aria2.getVersion",
 "params": [
  "token:s3cret"
 ]
}
{
 "id": "1",
 "jsonrpc": "2.0",
 "result": {
  "enabledFeatures": [
   "Async DNS",
   "BitTorrent",
   "Firefox3 Cookie",
   "GZip",
   "HTTPS",
   "Message Digest",
   "Metalink",
   "XML-RPC",
   "SFTP"
  ],
  "version": "1.37.0"
 }
}
aria2.getSessionInfo () → sessionId An ID that changes each time aria2 starts.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "2",
 "method": "aria2.getSessionInfo",
 "params": [
  "token:s3cret"
 ]
}
{
 "id": "2",
 "jsonrpc": "2.0",
 "result": {
  "sessionId": "c25a0a2ad315b68eb70f9ec1479050ff9f2b6399"
 }
}
aria2.saveSession () → "OK" Writes the session file now. Needs --save-session to be set.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "s",
 "method": "aria2.saveSession",
 "params": [
  "token:s3cret"
 ]
}
{
 "id": "s",
 "jsonrpc": "2.0",
 "result": "OK"
}
aria2.shutdown () → "OK" Stops aria2 cleanly, like pressing Ctrl+C once.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "37",
 "method": "aria2.shutdown",
 "params": [
  "token:s3cret"
 ]
}
{
 "id": "37",
 "jsonrpc": "2.0",
 "result": "OK"
}
aria2.forceShutdown () → "OK" Stops aria2 at once, without the clean-up steps.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "z",
 "method": "aria2.forceShutdown",
 "params": [
  "token:s3cret"
 ]
}
{
 "id": "z",
 "jsonrpc": "2.0",
 "result": "OK"
}

System methods

system.multicall ([{methodName, params}, …]) → list of results Runs several methods in one request.

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "m",
 "method": "system.multicall",
 "params": [
  [
   {
    "methodName": "aria2.getGlobalStat",
    "params": [
     "token:s3cret"
    ]
   },
   {
    "methodName": "aria2.addUri",
    "params": [
     "token:s3cret",
     [
      "https://example.com/small3.bin"
     ],
     {
      "pause": "true"
     }
    ]
   }
  ]
 ]
}
{
 "id": "m",
 "jsonrpc": "2.0",
 "result": [
  [
   {
    "downloadSpeed": "0",
    "numActive": "0",
    "numStopped": "0",
    "numStoppedTotal": "0",
    "numWaiting": "0",
    "uploadSpeed": "0"
   }
  ],
  [
   "9a1c64aae2e967ce"
  ]
 ]
}
system.listMethods () → method names The names of all methods. Works without a token. · No token needed

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "22",
 "method": "system.listMethods",
 "params": []
}
{
 "id": "22",
 "jsonrpc": "2.0",
 "result": [
  "aria2.addUri",
  "aria2.addTorrent",
  "aria2.getPeers",
  "aria2.addMetalink",
  "…"
 ]
}
system.listNotifications () → notification names The names of all notifications. Works without a token. · No token needed

Real request and reply

{
 "jsonrpc": "2.0",
 "id": "23",
 "method": "system.listNotifications",
 "params": []
}
{
 "id": "23",
 "jsonrpc": "2.0",
 "result": [
  "aria2.onDownloadStart",
  "aria2.onDownloadPause",
  "aria2.onDownloadStop",
  "aria2.onDownloadComplete",
  "aria2.onDownloadError",
  "aria2.onBtDownloadComplete"
 ]
}

Notifications: let aria2 tell you

Over WebSocket, aria2 sends a message when something happens to a download, so your program does not need to poll. Each carries the GID; call aria2.tellStatus for details.

  • aria2.onDownloadStartA download started, or resumed after a pause.
  • aria2.onDownloadPauseA download was paused.
  • aria2.onDownloadStopA download was stopped by you (removed).
  • aria2.onDownloadCompleteA download finished. For torrents: after seeding ends.
  • aria2.onDownloadErrorA download failed. tellStatus shows errorCode and errorMessage.
  • aria2.onBtDownloadCompleteA torrent finished downloading; seeding starts now.
{"jsonrpc":"2.0","method":"aria2.onDownloadStart","params":[{"gid":"35b6f22ff341c545"}]}
{"jsonrpc":"2.0","method":"aria2.onDownloadComplete","params":[{"gid":"4792fc4fda863437"}]}
{"jsonrpc":"2.0","method":"aria2.onDownloadPause","params":[{"gid":"35b6f22ff341c545"}]}

Download states

The status field of tellStatus is always one of these six:

  • activeDownloading or seeding now.
  • waitingIn the queue, waiting for a free slot (max-concurrent-downloads).
  • pausedPaused by you.
  • errorStopped because of an error; errorCode holds the exit code.
  • completeFinished.
  • removedRemoved by you. Its errorCode is 31.

Errors and what they mean

Errors come back as an error object instead of result. These are the ones we triggered:

aria2 saysCause and fix
UnauthorizedThe token is wrong or missing. Send token: followed by exactly the value of --rpc-secret as the first parameter.
GID … is not foundThe GID is wrong, or the download finished and was purged. Finished downloads stay only until purged (max-download-result, default 1000).
No such method: …A typo in the method name. Names are case-sensitive: aria2.addUri, not aria2.adduri.
Parse error. (code -32700)The body is not valid JSON. Check the quotes; in a shell, wrap the JSON in single quotes.
We encountered a problem while processing the option …An option value aria2 does not accept. Check its accepted values in the options reference.
Filename is not given.aria2.saveSession without --save-session. Start aria2 with a session file.
The parameter at 0 has wrong type.A token was put at the top of system.multicall. The token goes inside each inner call.

From Python and Node.js

No extra libraries needed. Both examples ran against aria2 1.37.0 as shown, with only the URL changed.

Python 3 (standard library)
import json
import urllib.request

RPC = "http://localhost:6800/jsonrpc"
TOKEN = "token:s3cret"

def call(method, *params):
    body = json.dumps({"jsonrpc": "2.0", "id": "py", "method": method,
                       "params": [TOKEN, *params]}).encode()
    with urllib.request.urlopen(RPC, body) as r:
        reply = json.load(r)
    if "error" in reply:
        raise RuntimeError(reply["error"]["message"])
    return reply["result"]

gid = call("aria2.addUri", ["https://example.com/file.iso"], {"split": "16"})
status = call("aria2.tellStatus", gid, ["status", "completedLength", "totalLength"])
print(gid, status)
Node.js 22+ (built-in fetch and WebSocket)
// Node.js 22+: fetch and WebSocket are built in.
const RPC = 'http://localhost:6800/jsonrpc';
const TOKEN = 'token:s3cret';

async function call(method, ...params) {
  const res = await fetch(RPC, { method: 'POST', body: JSON.stringify({ jsonrpc: '2.0', id: 'js', method, params: [TOKEN, ...params] }) });
  const reply = await res.json();
  if (reply.error) throw new Error(reply.error.message);
  return reply.result;
}

// Get told when a download finishes instead of polling.
const ws = new WebSocket('ws://localhost:6800/jsonrpc');
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.method === 'aria2.onDownloadComplete') console.log('done:', msg.params[0].gid);
};

const gid = await call('aria2.addUri', ['https://example.com/file.iso']);
console.log('added', gid);

Ready-made clients exist too: aria2p for Python, and the code inside AriaNg and our WebUI for the browser.

Keep it safe

  • Always set --rpc-secret. Without it, anyone who reaches the port can make aria2 download files to your disk and run its hook commands.
  • Keep the port on your own machine or a trusted network. Never forward port 6800 to the internet.
  • For remote access, put aria2 behind HTTPS: --rpc-secure with a certificate, or a reverse proxy such as nginx (our Docker guide has a tested setup).
  • --rpc-allow-origin-all=true lets any web page in your browser call aria2. Use it only together with a secret.

Questions

What is the default aria2 RPC port?
6800. Change it with --rpc-listen-port. The JSON-RPC path is /jsonrpc and the XML-RPC path is /rpc.
Why does my request return Unauthorized?
aria2 was started with --rpc-secret and your request does not carry it. Put "token:YOUR_SECRET" as the first element of params. system.listMethods and system.listNotifications are the only calls that work without it.
Why do option values have to be strings?
The aria2 manual defines option values as strings, and aria2 parses them the same way as on the command line. Send {"split": "16"}, not {"split": 16}.
Can a web page call aria2 directly?
Yes, if aria2 runs with --rpc-allow-origin-all=true so the browser allows the request. That is how AriaNg and our online WebUI work. Keep a secret set.
How do I know when a download is finished?
Connect over WebSocket and wait for aria2.onDownloadComplete, or poll aria2.tellStatus and check for status "complete". A hook (--on-download-complete) works without any RPC code.

Related