Tutto quello che ti serve per usare l'API senza essere admin: come autenticarti, e soprattutto come esplorare le tue cartelle e i tuoi file. Ogni esempio qui sotto è provabile dal vivo: incolla la tua chiave e premi Esegui.
Da utente non-admin NON usi username e password. Il modello è:
| Contesto | Come ti autentichi |
|---|---|
| Nel browser (pannello) | Login con Telegram (il bottone "Login con Telegram"). Il pannello ottiene un token di sessione (JWT). |
| Da script / widget / app | Una chiave API xfsk_… che generi nel pannello, inviata nell'header X-API-Key. |
X-API-Key per ogni richiesta. È tutto qui.X-API-Key: xfsk_la_tua_chiave
L'admin in più può autenticarsi con POST /auth/login (username/password). A te non serve.
Primo test utile: verifica che la chiave funzioni e scopri il tuo user_id.
{
"user_id": 5729584516,
"telegram_id": 5729584516,
"username": "mojibakex",
"first_name": "Mojibake",
"is_admin": false,
"is_authorized": true,
"total_downloads": 135
}
Questo è il punto chiave. Le cartelle sono piatte in una lista: ognuna ha un id e un
parent_id. La gerarchia la ricostruisci tu collegando parent_id → id.
parent_id = 0 → cartella di primo livello (radice).parent_id = 14 → è dentro la cartella con id = 14.{
"folders": [
{ "id": 14, "parent_id": 0, "name": "facebook", "is_system": true, "user_id": "5729584516" },
{ "id": 46, "parent_id": 14, "name": "Linda Stabilini DJ","is_system": false, "user_id": "5729584516" },
{ "id": 138,"parent_id": 137,"name": "Hunter X Hunter", "is_system": false }
]
}
Campi: id, parent_id, name, is_system (cartelle automatiche es. "facebook", "youtube"),
color, icon, created_at, metadata.
Una volta che hai gli id delle cartelle, chiedi i file con il parametro folder_id:
| Chiamata | Cosa restituisce |
|---|---|
/fm/files (senza parametro) | TUTTI i tuoi file, in ogni cartella. |
/fm/files?folder_id=0 | Solo i file nella radice (non in una cartella). |
/fm/files?folder_id=14 | I file dentro la cartella 14. |
/fm/files?search=dylan | Ricerca per nome (combinabile con folder_id). |
/fm/files?tag_id=3 | File con quel tag. |
/fm/files?limit=10 | Solo i 10 più recenti. Si combina con tutti gli altri parametri. |
/fm/files?limit=10&offset=10 | I dieci successivi: è così che si sfoglia a pagine. |
/fm/files?limit=0 | Nessun file, solo il conteggio: utile per sapere quanti sono. |
Nella risposta, count è quanti file ti sono arrivati davvero e
total quanti ne esistono con quei filtri. Senza limit i due
numeri coincidono. L’ordine è sempre dal più recente al più vecchio.
{
"files": [
{
"id": 3166,
"filename": "2026-06-22_1659744378594844.mp4",
"filesize": 17876784,
"folder_id": 14,
"source": "facebook",
"is_favorite": false,
"channel_msg_id": 9747562496,
"created_at": "2026-06-27T18:35:09",
"tag_ids": []
}
],
"count": 3
}
folder_id=0), la cartella facebook (id 14) ne ha 3,
Hunter X Hunter (id 138) ne ha 110.Per "navigare" come in un file manager, scarichi le cartelle una volta e le colleghi via parent_id.
Premi qui sotto per farlo dal vivo con il tuo account:
const { folders } = await (await fetch('/api/v1/fm/folders',
{ headers:{ 'X-API-Key': KEY } })).json();
// indicizza per id e raggruppa per parent_id
const byParent = {};
for (const f of folders) (byParent[f.parent_id] ||= []).push(f);
function print(parent = 0, depth = 0) {
for (const f of (byParent[parent] || [])) {
console.log(' '.repeat(depth) + '📁 ' + f.name + ' #' + f.id);
print(f.id, depth + 1); // ricorsione sui figli
}
}
print(); // parte dalla radice (parent_id = 0)
{ "name": "Le mie serie", "parent_id": 0 }
Ometti o metti parent_id: 0 per crearla in radice; mettine uno esistente per annidarla.
{ "file_ids": [3166, 2588], "folder_id": 14 }
Sposta uno o più file nella cartella indicata (folder_id: 0 = riportali in radice).
| Cosa | Endpoint |
|---|---|
| Scaricare un file | GET /api/v1/fm/files/<id>/stream |
| Avviare un download da URL | POST /api/v1/downloads |
| Stato dei download | GET /api/v1/downloads |
| Aggiungere un magnet/torrent | POST /api/v1/torrents |
| Creare un link di condivisione | POST /api/v1/shares |
| Eventi in tempo reale (progresso) | GET /api/v1/events (SSE) |
| Gestire le tue chiavi | GET /api/v1/keys |
Con EventSource la chiave va in query (il browser non manda header sugli SSE):
const ev = new EventSource('/api/v1/events?api_key=' + KEY);
ev.onmessage = e => console.log(JSON.parse(e.data));
Il riferimento completo di tutti gli endpoint è in 📖 Documentazione.
Oltre agli script, puoi incollare un widget pronto nel tuo sito: i visitatori incollano dei link e ricevono link diretti temporanei, senza login e senza vedere la tua chiave (le richieste passano dal server).
| Passo | Cosa fare |
|---|---|
| 1 · Genera la chiave | Pannello → API & Widget → Genera nuova chiave. Metti un’etichetta e i domini del sito. Copia subito la chiave xfsk_…: si vede una sola volta. |
| 2 · Genera il codice | Sempre lì → Generatore codice widget: scegli il widget, incolla la chiave nel campo apposito e copia il blocco <script>. |
| 3 · Incolla nel sito | Metti il blocco dove vuoi il widget. Fatto. |
<div id="xfs-widget"></div>
<script src="https://iltuoserver/assets/embed.js"
data-widget="multi-dl"
data-api-key="xfsk_LA_TUA_CHIAVE"
data-target="#xfs-widget"
data-accent="#3b82f6"></script>
<script> non ha una chiave valida. Controlla in ordine:
data-api-key="xfsk_LA_TUA_CHIAVE" → mettici la tua chiave.?key=LA_TUA_CHIAVE in fondo all’URL.Sì. Nel pannello → API & Widget → Le tue chiavi trovi tutte le chiavi generate,
mostrate solo mascherate (es. xfsk_ab12cd34••••••) perché la chiave intera non è più
recuperabile dopo la creazione. Per ognuna puoi:
| Azione | Effetto |
|---|---|
| Salva domini | Aggiorna i domini autorizzati (CORS) da cui il widget può girare. |
| Revoca chiave | Disattiva subito la chiave: widget e script che la usano smettono di funzionare. Irreversibile. |
Anche via API: GET /api/v1/keys (elenco mascherato) ·
POST /api/v1/keys (crea) ·
DEL /api/v1/keys/<id> (revoca).
XFS Bot · guida utente · gli esempi marcati ▶ girano sul server in tempo reale.