Integrate with the dnfme.fail platform to manage your site's mirror URLs programmatically. Keep your listings up-to-date with our secure API.
The API allows you to perform full CRUD (Create, Read, Update, Delete) operations on your mirror URLs. This ensures that our listings remain current and accurate.
The API uses Bearer token authentication and requires all request bodies to be sent as JSON.
All API requests must include an authorization header with your unique API token:
The base URL for all endpoints is: https://dnfme.fail/api
Retrieve a list of all current mirrors associated with your API token.
{
"message": "Mirrors retrieved successfully",
"mirrors": [
{
"id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
"url": "http://mirror-one.onion",
"captcha_required": false,
"signature": "This is a signed message for mirror one."
},
{
"id": "b2c3d4e5-f6a7-8901-2345-67890abcdef1",
"url": "http://mirror-two-requires-captcha.onion",
"captcha_required": true,
"signature": ""
}
]
}
Add one or more new mirror URLs to your existing list. Duplicates will be ignored.
The request body must contain a `mirrors` key with an array of mirror objects. The `id` is generated by the server and should be omitted.
{
"mirrors": [
{
"url": "http://newmirror1.onion",
"captcha_required": false,
"signature": "Optional signed message."
},
{
"url": "http://newmirror2.onion",
"captcha_required": true,
"signature": ""
}
]
}
{
"message": "Mirrors added successfully",
"mirrors": [
// ... existing mirrors ...
{
"id": "c3d4e5f6-a7b8-9012-3456-7890abcdef12",
"url": "http://newmirror1.onion",
"captcha_required": false,
"signature": "Optional signed message."
},
{
"id": "d4e5f6a7-b8c9-0123-4567-890abcdef123",
"url": "http://newmirror2.onion",
"captcha_required": true,
"signature": ""
}
]
}
Replace your entire list of mirrors with a new one.
Provide the complete new list of mirrors. An `id` will be generated for any mirror that does not have one.
{
"mirrors": [
{
"url": "http://onlymirror.onion",
"captcha_required": true,
"signature": "This is the only mirror now."
}
]
}
{
"message": "Mirrors replaced successfully",
"mirrors": [
{
"id": "e5f6a7b8-c9d0-1234-5678-90abcdef1234",
"url": "http://onlymirror.onion",
"captcha_required": true,
"signature": "This is the only mirror now."
}
]
}
Remove one or more specific mirrors from your list using their unique IDs.
Provide an array of mirror IDs you wish to delete.
{
"ids": [
"a1b2c3d4-e5f6-7890-1234-567890abcdef"
]
}
{
"message": "Mirrors deleted successfully",
"mirrors": [
// ... remaining mirrors ...
]
}
To make interacting with the API easier, we provide an advanced Bash script that handles all CRUD operations and the new data structure.
You need to have curl and jq installed.
# On Debian/Ubuntu sudo apt-get update && sudo apt-get install curl jq # On macOS (using Homebrew) brew install curl jq
Save the following code into a file named mirror-manager.sh.
#!/bin/bash
# ==============================================================================
# mirror-manager.sh v2.0
#
# An advanced Bash script to manage mirror URLs via the dnfme.fail API,
# supporting captcha flags and signed messages.
#
# Dependencies: curl, jq
# Author: DarknetDotFail
# Date: September 17, 2025
# ==============================================================================
# --- Configuration ---
API_BASE_URL="https://dnfme.fail/api"
# --- Helper Functions ---
usage() {
echo "A command-line client for the dnfme.fail Mirror API."
echo ""
echo "Usage: $0 [options] [arguments...]"
echo ""
echo "Commands:"
echo " list List all current mirrors."
echo " add [mirror_data...] Add one or more mirrors."
echo " replace [mirror_data...] Replace the entire mirror list."
echo " delete [id2...] Delete mirrors by their unique ID."
echo ""
echo "Mirror Data Format for 'add' and 'replace':"
echo " A sequence of mirrors, each potentially preceded by flags."
echo " [--captcha] [--sig \"message\"] "
echo ""
echo "Options for 'add' and 'replace':"
echo " --captcha Set 'captcha_required' to true for the *next* URL."
echo " --sig \"your message\" Set a signature for the *next* URL."
echo ""
echo "Examples:"
echo " # List mirrors"
echo " $0 list YOUR_API_TOKEN"
echo ""
echo " # Add a simple mirror"
echo " $0 add YOUR_API_TOKEN http://new1.onion"
echo ""
echo " # Add a mirror that requires a CAPTCHA"
echo " $0 add YOUR_API_TOKEN --captcha http://new2.onion"
echo ""
echo " # Add a mirror with a signature"
echo " $0 add YOUR_API_TOKEN --sig \"This is a signed message\" http://new3.onion"
echo ""
echo " # Add multiple mirrors with different properties"
echo " $0 add YOUR_API_TOKEN http://a.onion --captcha http://b.onion --sig \"sig\" --captcha http://c.onion"
echo ""
echo " # Delete mirrors by ID"
echo " $0 delete YOUR_API_TOKEN a1b2c3d4-e5f6... b2c3d4e5-f6a7..."
}
check_dependencies() {
if ! command -v curl &> /dev/null; then echo "Error: 'curl' is not installed." >&2; exit 1; fi
if ! command -v jq &> /dev/null; then echo "Error: 'jq' is not installed." >&2; exit 1; fi
}
# --- API Functions ---
API_TOKEN=""
make_request() {
local method="$1"
local endpoint="$2"
local data="$3"
local args=(-s -X "$method" "${API_BASE_URL}${endpoint}")
args+=(-H "Authorization: Bearer ${API_TOKEN}")
args+=(-H "Accept: application/json")
if [[ -n "$data" ]]; then
args+=(-H "Content-Type: application/json")
args+=(-d "$data")
fi
curl "${args[@]}" | jq
}
# --- Main Script Logic ---
check_dependencies
if [ "$#" -lt 2 ]; then
usage
exit 1
fi
COMMAND="$1"
API_TOKEN="$2"
shift 2
case "$COMMAND" in
list)
echo "Fetching mirror list..."
make_request "GET" "/mirrors"
;;
add | replace)
if [ "$COMMAND" == "add" ]; then
echo "Adding new mirrors..."
HTTP_METHOD="POST"
else
echo "Replacing all mirrors..."
HTTP_METHOD="PUT"
fi
captcha_flag=false
signature=""
json_objects=""
while [ "$#" -gt 0 ]; do
case "$1" in
--captcha)
captcha_flag=true
shift
;;
--sig)
signature="$2"
shift 2
;;
*)
url="$1"
# Escape quotes in signature
escaped_sig=$(echo "$signature" | sed 's/"/\\"/g')
json_object=$(cat <&2
usage
exit 1
fi
payload="{\"mirrors\": [${json_objects%,}]}"
make_request "$HTTP_METHOD" "/mirrors" "$payload"
;;
delete)
echo "Deleting specified mirrors..."
ids=("$@")
if [ ${#ids[@]} -eq 0 ]; then
echo "Error: The 'delete' command requires at least one mirror ID." >&2
usage
exit 1
fi
json_array=$(printf '"%s",' "${ids[@]}")
payload="{\"ids\": [${json_array%,}]}"
make_request "DELETE" "/mirrors" "$payload"
;;
*)
echo "Error: Unknown command '$COMMAND'" >&2
usage
exit 1
;;
esac
First, make the script executable:
chmod +x mirror-manager.sh
Then, run the script with the desired command. Replace YOUR_API_TOKEN with your actual token.
./mirror-manager.sh list YOUR_API_TOKEN
Use flags to set properties: --captcha for CAPTCHA and --sig "message" for a signature.
./mirror-manager.sh add YOUR_API_TOKEN \ http://new1.onion \ --captcha http://new2.onion \ --sig "Signed message" http://new3.onion \ --captcha --sig "Both flags" http://new4.onion
The `replace` command works just like `add`.
./mirror-manager.sh replace YOUR_API_TOKEN --captcha http://main.onion
./mirror-manager.sh delete YOUR_API_TOKEN ID_1 ID_2