HTTP API

cross-seed has an HTTP API as part of Daemon Mode. When you run the cross-seed daemon command, the app starts an HTTP server, listening on port 2468 (configurable with the port option).

tip

You can easily configure your torrent client to send search commands when a torrent finishes.

Authorization

You can enable/disable the apiAuth option to toggle authorization on all HTTP requests made to the cross-seed daemon.

info

apiAuth is enabled in the config file by default, if you want to disable apiAuth set it to false.

danger

Even with API auth enabled, we still recommend that you do not expose its port to untrusted networks (such as the Internet).

To find your API key, run the cross-seed api-key command. The api key can be included with your requests in either of two ways:

# provide api key as a query param
curl -XPOST localhost:2468/api/webhook?apikey=YOUR_API_KEY --data-urlencode ...
# provide api key as an HTTP header
curl -XPOST localhost:2468/api/webhook -H "X-Api-Key: YOUR_API_KEY" --data-urlencode ...

POST /api/webhook

This endpoint invokes a search, on all configured trackers, for a specific torrent name, infoHash, or torrent data. You can provide the name directly, or you can provide an infoHash or path to search for, which cross-seed will use to either look up the torrent in your torrentDir or parse the filename directly. It will respond with 204 No Content once it has received your request successfully.

tip

Searches that match a torrent file always take precedence, even in data-based searching.

Supported formats

Content-Type	Supported
application/json	✅
application/x-www-form-urlencoded	✅

Request Payload

POST /api/webhook
{
    // one of { name, infoHash, path } is required
    name: "<torrent name here>",
    infoHash: "<infoHash of torrent>",
    path: "/path/to/torrent/file.mkv",
    outputDir: "/path/to/output/dir", // optional
}

curl -XPOST http://localhost:2468/api/webhook \
  --data-urlencode 'name=<torrent name here>' \
  --data-urlencode 'outputDir=/path/to/output/dir'

Alternatively, you can use JSON:

curl -XPOST http://localhost:2468/api/webhook \
  -H 'Content-Type: application/json' \
  --data '{"name":"<torrent name here>"}'

POST /api/announce

Use this endpoint to feed announces into cross-seed. For each announce, cross-seed will check if the provided search criteria match any torrents you already have. If found, it will run the matching algorithm to verify that the torrents do match, and download/inject the announced torrent.

tip

This is a real-time alternative to scanning RSS feeds. Consider turning the RSS scan off (rssCadence: null,) if you set up this feature.

This endpoint returns 200 if your request was received and a match was found. If no match it responds with 204 No Content.

Supported formats

Content-Type	Supported
application/json	✅
application/x-www-form-urlencoded	✅

Request Payload

POST /api/announce
{
    "name": "string", // torrent name
    "guid": "string", // ideally the torrent's comments/listing url, would be for caching purposes
    "link": "string", // download link
    "size": "number", // in bytes
    "tracker": "string" // this is for logging purposes
}