[Ex]Freedomist API

This page contains a description of the exfreedomist.com API service operation and additional information about the data model, index, and stability. The complete schema is available at /api_swagger + openapi.json .

Registration and Access

Access to API methods requires individual approval by the administration after registration and verification of an account on download.exfreedomist.com.

After access is granted, you will be able to issue and revoke your own authorization tokens for the API. Your personal account will feature a API management section with the following links:

  • API stats: usage statistics.
  • API tokens: token management.

When creating a token, you may select the token's validity period (unlimited by default), the request limit per token (unlimited by default), and its status (active or inactive). The validity period and request limit are not tied to your account parameters in any way and operate independently.

You will be able to make API requests for the duration of your subscription, until you exhaust the overall request limit for your account.

Request Accounting

The billing system accounts for all API requests, except:

  • those returning a 5XX error code (internal server errors);
  • those returning a 401 error code (authorization errors). Apart from an invalid token, this error is also caused by the exhaustion of the token's or user's request limit, expiration of the token's validity period or the user's subscription, attempts to use an inactive token, or a mismatch between the endpoint scope and the token.

In addition to the statistics available in your personal account on the website, you can check the remaining number of requests from the headers of successful server responses:

  • X-API-User-Requests contains the number of API requests available for the current user,
  • X-API-Token-Requests contains the number of API requests available for the current token, or "Infinity" for tokens with no request limit.

The data in the X-API-User-Requests and X-API-Token-Requests headers reflects the state before the request is executed.

Authorization

Access to API methods requires one of the following request authorization methods:

  • The X-API-Key HTTP request header;
  • The token request parameter.

Using one of these methods is sufficient. If multiple methods are used simultaneously, you must ensure that the authorization tokens match; otherwise, an error with a 401 code will be returned.

Schema Comments

SearchResponseItem:

  • magnet_key — a one-time identifier for accessing direct information about the magnet_link and infohash of the torrent. Used in /api/magnet ;
  • is_alive — indicates the presence of seeders recently. If false, a request to /api/files for the corresponding infohash will likely return a 404 error;
  • category — the tracker section where the torrent was published. Typically contains the format or genre name;
  • cached — indicates whether the torrent is cached by the Telegram bot . Possible values: full (fully cached), partial (partially cached), empty (not cached);
  • downloads — the number of times the torrent has been downloaded by users, according to the source;
  • seeders — the number of seeders, according to the source;
  • status — torrent statuses according to the source. This parameter is usually related to the quality of the torrent's presentation on a given tracker and is NOT related to the availability or access speed of the torrent. Learn more about the meaning of statuses;
  • metric — the relevance metric for the query.

Query Language

The following applies to the query parameter of the SearchQueryModel schema for /api/search .

Spaces in the query represent a logical "AND". For example, searching for the phrase mp3 metal 2025 will find torrents that have mp3 AND metal AND 2025 simultaneously in the title, category, and/or content.

You can exclude a word from the results using the ! operator. For example, searching for the phrase mp3 metal !2025 will find torrents that have mp3 AND metal, but do not have 2025 in the indexed fields.

Index and Relevance

The indexed data fields for POST /search search queries are title and category.

When sorting by relevance, more accurate matches to the search phrase will appear above less accurate ones. The relative position of words in the query is taken into account. The weights for matches in the title and category are in a 2:1 ratio, respectively.

Stability and Planned Changes

Future plans include:

  • increasing the number of available scope values;
  • extending /search , Filter schema: currently the only type is numeric. Significant changes to the Filter schema and its dependencies are expected;
  • adding the ability to control which fields are returned in certain endpoints;
  • adding the ability to control which fields are indexed;
  • enhancements to the query language.

Full backward compatibility for API versions is guaranteed starting from API version 1.0.0. We notify you of all planned API changes that affect the schema via the mailing list sent to the email address associated with your account.