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).
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).
API authorization using an API key is now mandatory as of v6. The apiAuth
option has been
deprecated and removed.
Even with API authorization, we still recommend that you do not expose its port to untrusted networks (such as the Internet).
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.
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
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 '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.
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
.
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", // 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
}