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 specify an API key using the apiKey option, or let cross-seed generate one for you (default).

To find your generated 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 infoHash or torrent data. cross-seed will 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
{
	// infoHash or path is required but not both (infoHash is recommended)
	infoHash: "<infoHash of torrent>",
	path: "/path/to/torrent/file.mkv",
}

curl -XPOST http://localhost:2468/api/webhook \
  --data-urlencode 'infoHash=<torrent infoHash 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 '{"infoHash":"<torrent infoHash 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 our matching algorithm to verify that the torrents do indeed match, and inject the announced torrent.

info

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

This endpoint returns 200 if your request was received and a completed match was found in your client, if a match was found to be incomplete (still downloading) then cross-seed will return the status code 202, and if no match was found cross-seed will respond with a 204 No Content.

tip

The most common way to implement an "announce feed" is utilizing autobrr.

You can use the "retry on status code" function (code: 202) in autobrr's filter settings to retry currently incomplete (downloading) torrents

Supported formats

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

Request Payload

POST /api/announce
{
	"name": "string", // torrent name
	"guid": "string", // usually the download link, used for caching purposes
	"link": "string", // download link
	"tracker": "string" // used for linking path and logging
}