Référence API

Référence API

Toutes les routes vivent sous app/api/. Les messages d'erreur du serveur sont en français (reproduits tels quels ci-dessous).

Modèles d'authentification

Modèle	Vérification	Utilisé par
Session (NextAuth)	await auth()	la plupart des routes de gestion
Session + admin	session.user.role === "admin"	/api/admin/*, parties de /api/settings/*
Clé API (en-tête)	x-api-key → data/api-keys.json	/api/upload uniquement
Clé API (form-data)	champ apiKey	/api/colors
Public	aucune	service de fichiers, flux SSE, /api/public/*, auth

---

POST /api/upload

Upload principal (ShareX / fu / mobile). Auth : en-tête x-api-key.

Requête : multipart/form-data, champ fichier file.

Pipeline : présence de la clé → présence du fichier → validation de la clé (existence, expiration, permission selon l'extension, MAJ lastUsed) → types autorisés (config) → limites de taille → stockage (+ traitement par modules pour les images) → miniature (Sharp, si image) → jeton de suppression → historique → revalidation + diffusion SSE.

Succès 200

{
  "url": "<url du fichier>",
  "thumbnail_url": "<url miniature | null>",
  "deletion_url": "<url>?token=<token>",
  "key": { "name": "<nom de la clé>", "lastUsed": "<ISO>" }
}

Erreurs

Code	error	Déclencheur
401	Clé API manquante	en-tête x-api-key absent
400	Aucun fichier fourni	champ file absent
403	Clé API invalide ou permissions insuffisantes	clé inconnue / expirée / sans permission
400	L'upload d'images n'est pas autorisé	images désactivées en config
400	L'upload de documents n'est pas autorisé	documents désactivés
400	L'upload d'archives n'est pas autorisé	archives désactivées
400	Type de fichier non supporté	extension hors images/docs/archives
400	La taille du fichier est inférieure à la limite minimale de {n}KB	trop petit
400	La taille du fichier dépasse la limite de {n}MB	trop grand
400	<message>	échec d'écriture (ex. nom déjà existant)
500	Une erreur est survenue lors de l'upload	exception

---

Clés API

Route	Méthode	Auth	Description
/api/api-keys	GET	session	Liste les clés (objets complets)
/api/api-keys	POST	session	Crée une clé { name, permissions, expiresAt? } → renvoie la clé
/api/api-keys/[id]	DELETE	session	Supprime une clé (204, ou 404 Clé non trouvée)

Modèle stocké (data/api-keys.json) : { id:"key_…", name, key:"sk_…", createdAt, expiresAt|null, createdBy, permissions, lastUsed? }.

---

Fichiers & albums (session)

Route	Méthodes	Notes
/api/files	GET, POST, PUT, DELETE	liste paginée (page,q,secure,starred,sort,order) ; PAGE_SIZE=12
/api/files/[filename]	GET, DELETE	GET public ; DELETE via session ou ?token=
/api/files/[filename]/metadata	GET	métadonnées du fichier
/api/files/[filename]/security	PUT	bascule « sécurisé » (déplace dans secure/)
/api/files/[filename]/star	PUT	bascule favori
/api/files/batch	POST	actions de masse (ajout/retrait d'album)
/api/albums	GET, POST	liste / création d'album
/api/albums/[id]	GET, PUT, DELETE	+ contrôle de propriétaire (403) ; isPublic génère un publicSlug
/api/albums/[id]/files	GET, POST, DELETE	fichiers de l'album
/api/thumbnails/[filename]	GET (public)	miniature 300px JPEG, Cache-Control: 1 an

---

Galerie, statistiques, historique, couleurs

Route	Méthode	Auth	Réponse
/api/gallery/upload	POST	session	upload web → { url, thumbnailUrl, deletionToken }
/api/gallery/process	POST	session	retraite une image existante
/api/gallery/stream	GET	public SSE	flux temps réel des nouveaux fichiers
/api/stats	GET	session	totaux, par extension, distribution, croissance, uploadsByMethod
/api/stats/geo	GET	session	{ topIps, geoMarkers }
/api/stats/stream	GET	public SSE	flux stats temps réel
/api/history	GET	session	historique paginé/filtrable
/api/history/[id]	DELETE	session (+owner/admin)	supprime une entrée
/api/colors	POST	session ou clé (apiKey)	{ colors:{ dominant, palette[], isDark } }

---

Catalogue public

Route	Méthode	Description
/api/public/catalog	GET	albums publics (+ images), pagination
/api/public/albums/[slug]	GET	un album public + ses fichiers

---

Modules (session)

GET /api/modules (liste), …/by-type, …/nav-items, …/ui, …/apply, …/call-function, …/enable|disable|[name]/toggle, …/install, …/[name]/settings (GET/PUT), …/[name]/data/[...path], …/[name]/delete. Voir Modules.

Admin & réglages (session + admin)

/api/admin/users (GET/POST/PUT/DELETE), /api/admin/logs (GET/DELETE), /api/admin/theme (GET/PUT), /api/settings/config (GET public lenient / PUT admin), /api/settings/domains (GET / POST·PUT·DELETE admin), /api/settings/theme (GET/PUT).

---

⚠️ À durcir avant une exposition publique (constaté dans le code) : PUT /api/settings/domains/config n'a aucune vérification d'auth ; GET /api/api-keys renvoie les clés en clair à toute session ; les uploads d'archives ne sont pas filtrés par une permission de clé ; extractColors n'est pas réellement imposé. Voir FAQ.