REST API

FatRat has a JSON API over HTTP. The web interface and fatrat-tui use it, and you can use it from scripts. This page shows how to reach it and gives a few examples. The complete description of every request and answer is the OpenAPI file on GitHub.

The API is part of the web interface, so FatRat must be built with the web interface.

Reaching the API

All paths start with /api/v1. There are two ways in.

Over the network

Turn on the web interface (see Running on a Server). The API is then on the same port, for example http://myserver:2233/api/v1/queues. Authentication is HTTP Basic: any user name, and the password from the web interface settings. If the password is empty, no authentication is needed. Without :PASSWORD, curl asks for it.

curl -u x:PASSWORD http://myserver:2233/api/v1/stats

A wrong or missing password gets status 401. Without HTTPS the password goes over the network unencrypted.

Over a unix socket

Start FatRat with --rest-socket path. The API is then also served on that socket, whether or not the web interface is on. The socket is created with mode 0600, so only the user FatRat runs as can use it, and it asks for no password. The system service uses /run/fatrat/rest.sock.

fatrat --nogui --rest-socket /run/user/1000/fatrat/rest.sock
curl --unix-socket /run/user/1000/fatrat/rest.sock http://localhost/api/v1/stats

The examples below use the socket. Over the network, replace --unix-socket path http://localhost with -u x:PASSWORD http://myserver:2233.

Rules for requests

• A request with a body must have the header Content-Type: application/json. The only exception is uploading a file, which uses multipart/form-data. Anything else gets status 415.
• If a request has an Origin header, it must name the same host as the Host header, or the request gets status 403. This stops web pages on other sites from using your browser's saved password. curl sends no Origin header.
• Queues and transfers are identified by their UUID, including the braces, for example {4829a1ca-60d7-432d-975d-74884b1adc42}. Give curl the option -g, or it reads the braces as a pattern. You can also write them as %7B and %7D.
• Speeds are in bytes per second. A limit of 0 means no limit.

Errors

When a request fails, the status is 4xx or 5xx and the body is an object with a stable code and a readable message:

{"error":{"code":"transfer_not_found","message":"Invalid transfer UUID"}}

Examples

List the queues

curl -g --unix-socket /run/fatrat/rest.sock http://localhost/api/v1/queues

The answer is an array with one object for each queue:

[{"uuid":"{4829a1ca-60d7-432d-975d-74884b1adc42}","name":"Main queue",
  "defaultDirectory":"/home/me/Downloads","moveDirectory":"",
  "watchDirectory":"","watchStatus":"off","upAsDown":false,
  "transferLimits":{"down":1,"up":1},"speedLimits":{"down":0,"up":0}}]

transferLimits is how many downloads and uploads of the queue may be active at once. speedLimits is the speed limit of the queue.

Add a link

Send one or more links to a queue. The answer has status 201 and lists the UUIDs of the new transfers. FatRat finds out whether each link is a plain download, a torrent or a Metalink. Add "paused":true to add the transfers without starting them, and "target" to save them somewhere other than the queue's default directory.

curl -g --unix-socket /run/fatrat/rest.sock \
     -X POST http://localhost/api/v1/queues/{4829a1ca-60d7-432d-975d-74884b1adc42}/transfers \
     -H 'Content-Type: application/json' \
     -d '{"urls":["http://example.org/file.iso"],"paused":true}'

{"uuids":["{ea1c4625-144d-438c-aa50-b2223ac7ee75}"]}

The other fields are upload (true to add an upload transfer), class (the transfer class, as listed by GET /api/v1/transfer-classes, instead of autodetecting) and speedLimits.

Upload a .torrent file

Send the file as a multipart/form-data form with the file in the part file and the options, as a JSON string, in the part options. The options are the same as for links, without urls (upload is ignored). curl -F makes this form:

curl -g --unix-socket /run/fatrat/rest.sock \
     -X POST http://localhost/api/v1/queues/{4829a1ca-60d7-432d-975d-74884b1adc42}/transfers \
     -F file=@ubuntu.torrent -F 'options={"paused":true}'

The answer is the same as for links. Metalink files work the same way. If you do not give a class and FatRat does not recognise the file as a torrent, a Metalink or a type that an extension handles, the answer is status 422 with no_matching_engine.

Pause and resume a transfer

Change the state of the transfer. The states you can set are Waiting (resume, in the queue's order), ForcedActive (start now, ignoring the queue's limits), Paused, Active, Failed and Completed. The answer is status 204 with no body.

curl -g --unix-socket /run/fatrat/rest.sock \
     -X PATCH http://localhost/api/v1/transfers/{ea1c4625-144d-438c-aa50-b2223ac7ee75} \
     -H 'Content-Type: application/json' -d '{"state":"Paused"}'

To change several transfers at once, send PATCH /api/v1/transfers with {"uuids":[...],"properties":{"state":"Paused"}}. The request is all or nothing: if it names a transfer that does not exist, or a value that is not valid, or a change fails part of the way, none of the transfers change. The same kind of request can set a comment, a completion command, a speed limit (userSpeedLimits) or move the transfers to another queue (queue).

Read a transfer with GET /api/v1/transfers/uuid. Its state is one of the states above; total and done are bytes.

Set a queue's watch folder

Change the watchDirectory of the queue to an absolute path. FatRat then adds the files you drop there (see Watch Folders). An empty string turns the watch folder off. The answer is the changed queue, whose watchStatus says whether the folder works: ok, missing, not_writable or duplicate. A relative path or a folder another queue watches is refused with status 422.

curl -g --unix-socket /run/fatrat/rest.sock \
     -X PATCH http://localhost/api/v1/queues/{4829a1ca-60d7-432d-975d-74884b1adc42} \
     -H 'Content-Type: application/json' -d '{"watchDirectory":"/srv/dropbox"}'

Create and delete a queue

curl -g --unix-socket /run/fatrat/rest.sock -X POST http://localhost/api/v1/queues \
     -H 'Content-Type: application/json' \
     -d '{"name":"Linux ISOs","speedLimits":{"down":102400,"up":0}}'

The answer has status 201 and describes the new queue. To delete a queue that still has transfers, say what happens to them, with ?moveTo=queue uuid or ?deleteTransfers=true. Without either, FatRat refuses with 409 queue_not_empty.

Other resources

The API covers everything the web interface does. The main paths are:

The OpenAPI file lists the paths, fields and error codes of all of these resources, including extensions, tasks and transfer actions. Tools such as Swagger UI can open it.