RPC Protocol

Risuko exposes a JSON-RPC 2.0 server over HTTP. The CLI uses this interface, and you can also build custom clients.

Connection

The RPC server listens on http://localhost:16800/jsonrpc by default.

Request Format

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "risuko.addUri",
  "params": [
    ["https://example.com/file.zip"],
    { "split": "16", "dir": "/downloads" }
  ]
}

Response Format

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": "a1b2c3d4e5f6"
}

Available Methods

Task Management

Queries

Options

Session

Task Routing

Pattern-based rules that override the download directory and assign a tag based on the inferred output filename. See the Task Routing guide.

A rule has the shape:

{
  "id": "rule-videos",
  "label": "Videos",
  "pattern": "*.{mp4,mkv,webm}",
  "dir": "/downloads/videos",
  "enabled": true
}

pattern is a case-insensitive glob (glob crate syntax) matched against the inferred filename only — not the URL or directory.

Example: curl

# Add a download
curl -X POST http://localhost:16800/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "risuko.addUri",
    "params": [["https://example.com/file.zip"], {"split": "16"}]
  }'

# Check status
curl -X POST http://localhost:16800/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "risuko.tellActive",
    "params": []
  }'

Error Responses

{
  "jsonrpc": "2.0",
  "id": "1",
  "error": {
    "code": -32600,
    "message": "GID a1b2c3d4 not found"
  }
}

Standard JSON-RPC error codes apply. Application-specific errors use codes in the -32000 to -32099 range.

aria2 Compatibility

The RPC server accepts both risuko.* and aria2.* method prefixes. For example, aria2.addUri is treated as risuko.addUri. This makes it compatible with existing aria2 RPC clients.

Authentication

When rpc-secret is set, every call must prefix its params array with "token:<secret>":

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "risuko.addUri",
  "params": ["token:my-secret", ["https://example.com/file.zip"]]
}

The token is stripped from params before dispatch. When rpc-secret is empty, the token: prefix is still accepted (and stripped) for compatibility with aria2 clients that always send one.

system.multicall

Batch any number of calls into a single round-trip. Per aria2 convention, the outer params array is not authenticated; each nested call is authenticated independently and must carry its own "token:<secret>" prefix when rpc-secret is set.

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "system.multicall",
  "params": [[
    { "methodName": "risuko.tellActive", "params": ["token:my-secret"] },
    { "methodName": "risuko.getGlobalStat", "params": ["token:my-secret"] }
  ]]
}

Returns an array where each element is either [result] (success) or { "code", "message" } (per-call error). The legacy ["token:...", [calls]] shape is also accepted, but the outer token is never trusted as authentication.

WebSocket Subscribe

The server upgrades GET /jsonrpc requests with a Connection: Upgrade / Upgrade: websocket header to a WebSocket. Once connected, the engine streams JSON-RPC notifications matching the aria2 event names — aria2.onDownloadStart, aria2.onDownloadPause, aria2.onDownloadStop, aria2.onDownloadComplete, aria2.onDownloadError, aria2.onBtDownloadComplete (each also published as risuko.on…) — for every task transition. Regular request/response calls also work over the same socket. Use system.listNotifications to enumerate the supported names.