API publique

1. Créer une clé API

Créez une clé depuis votre compte, avec les droits « lecture » et « téléchargement ». Elle n'est affichée qu'une seule fois : conservez-la comme un mot de passe. Envoyez-la dans l'en-tête Authorization.

Gérer mes clés API

export MODHUB_API_KEY=mhfr_…
curl -H "Authorization: Bearer $MODHUB_API_KEY" https://<domaine>/api/v1/me

2. Rechercher

La recherche tolère les fautes de frappe et se filtre par jeu, catégorie, type et langue. Tris : relevance, recent, updated, trending, popular, downloads. La pagination se fait par curseur (nextCursor).

curl -H "Authorization: Bearer $MODHUB_API_KEY" "https://<domaine>/api/v1/mods?q=armures&game=skyrimspecialedition&sort=popular&limit=20"

3. Lister les fichiers

Seuls les fichiers qui ont passé l'analyse de sécurité sont publiés. Chaque fichier a une catégorie (MAIN, OPTIONAL, UPDATE…), une version, une taille et son empreinte SHA-256.

curl -H "Authorization: Bearer $MODHUB_API_KEY" https://<domaine>/api/v1/mods/<id>/files

4. Télécharger

L'API répond par une redirection 302 vers une adresse signée, valable 5 minutes. Suivez-la sans renvoyer votre clé. Un fichier non analysé n'est jamais téléchargeable.

curl -H "Authorization: Bearer $MODHUB_API_KEY" -L -o mod.zip https://<domaine>/api/v1/files/<id>/download

5. Vérifier les mises à jour

Envoyez jusqu'à 100 empreintes SHA-256 (ou identifiants de fichiers) en un seul appel : pour chacune, l'API indique le fichier correspondant et la dernière version principale du mod.

curl -H "Authorization: Bearer $MODHUB_API_KEY" -H "Content-Type: application/json" \
  -d '{"sha256": ["9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"]}' \
  https://<domaine>/api/v1/files/check-updates

Gestionnaire de mods

STRD Core, le gestionnaire de mods de Shattered Universe (page « STRD Core »), ouvre les liens strd:// des boutons « Installer avec STRD Core » : fichiers seuls ou collections complètes (dans l'ordre des phases), avec la vérification des mises à jour.

strd://file/<id-du-fichier>
strd://collection/<id-de-la-collection>/<révision>

Erreurs

Toutes les erreurs ont le même format. Le code est stable et documenté ; le message est destiné aux développeurs.

{ "error": { "code": "FILE_NOT_CLEAN", "message": "…", "details": {} } }

Quotas

1 000 requêtes par heure et 20 000 par jour et par clé ; 300 téléchargements par heure. Les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset indiquent l'état du quota ; au-delà, l'API répond 429 avec Retry-After.

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 3542

Script d'exemple

Le dépôt contient un script Node.js complet (sans dépendance) qui enchaîne ces étapes : examples/api-quickstart.mjs.

MODHUB_API_URL=https://<domaine>/api/v1 MODHUB_API_KEY=mhfr_… \
  node examples/api-quickstart.mjs "armures" skyrimspecialedition