Documentation

API Eclipse v1

API REST JSON utilisée par le client Eclipse et par les intégrations tierces. Tous les endpoints sont préfixés par la base URL suivante :

Base URLhttps://api.eclipse.gg/api/v1

Protocole : HTTPS uniquement. Les réponses sont encodées en UTF-8. Les dates sont au format ISO 8601 UTC (2024-06-15T14:23:00Z). Les tailles sont exprimées en octets. Les checksums sont en sha256 hex minuscule.

i L'API est en accès ouvert pour la lecture. Les opérations d'écriture (upload, résolution de modpacks) nécessitent un Bearer token obtenu via /accounts/token.

Authentification

Passez votre token dans l'en-tête Authorization :

HTTP
Authorization: Bearer <token>

Les tokens sont générés depuis le tableau de bord. Durée de validité : 90 jours, renouvelable.

Rate limit

Les en-têtes de réponse suivants indiquent la consommation courante :

En-têteTypeDescription
X-RateLimit-LimitintegerQuota maximal par fenêtre (ex. 300)
X-RateLimit-RemainingintegerRequêtes restantes dans la fenêtre courante
X-RateLimit-Resetunix tsTimestamp UNIX de réinitialisation du compteur
Retry-AftersecondsPrésent uniquement lors d'un 429, délai d'attente

Le quota standard est de 300 req/min pour les requêtes authentifiées, 60 req/min pour les anonymes.

! En cas de dépassement, l'API retourne 429 Too Many Requests avec l'en-tête Retry-After. Implémentez un backoff exponentiel.

Format d'erreur

Toutes les erreurs suivent la structure immuable suivante :

JSON
{
  "error": {
    "code":    "NOT_FOUND",       // code machine, snake_case majuscule
    "message": "Project not found"  // message humain en anglais
  }
}
HTTPcodeSignification
400BAD_REQUESTParamètre manquant ou invalide
401UNAUTHORIZEDToken absent ou expiré
403FORBIDDENToken valide mais permissions insuffisantes
404NOT_FOUNDRessource inexistante
409CONFLICTDoublon (slug déjà pris, version existante…)
422UNPROCESSABLECorps JSON syntaxiquement valide mais sémantiquement rejeté
429RATE_LIMITEDQuota dépassé
500INTERNAL_ERRORErreur serveur interne

Pagination curseur

L'API utilise une pagination par curseur opaque (pas d'offset). Le corps de réponse d'une liste inclut :

JSON
{
  "items":          [...],       // tableau des résultats de la page
  "next_cursor":     "eyJpZCI6IjEyMyJ9", // null si dernière page
  "total_estimate": 1482          // estimation du total (peut varier)
}

Pour passer à la page suivante, transmettez la valeur de next_cursor dans le paramètre cursor de la requête suivante. Si next_cursor est null, vous avez atteint la fin.

i Ne parsez pas le curseur : il s'agit d'un token opaque base64 susceptible de changer de format sans préavis.
! total_estimate est une estimation — n'utilisez pas cette valeur pour des calculs de pagination stricte. Fiez-vous uniquement à next_cursor === null pour détecter la fin.

GET /search/suggest

Autocomplétion légère — retourne jusqu'à 8 suggestions de titres/slugs pour alimenter un champ de recherche en temps réel.

GET https://api.eclipse.gg/api/v1/search/suggest
ParamètreTypeDescription
qstringrequisPréfixe à compléter (min 2 caractères)
kindenumoptionnelFiltre sur le type de projet
limitintegeroptionnel1–8, défaut 5
JSON — Réponse
{
  "suggestions": [
    { "id": "AANobbMI", "slug": "sodium", "title": "Sodium", "kind": "mod" },
    { "id": "P7dR8mSH", "slug": "sodium-extra", "title": "Sodium Extra", "kind": "mod" }
  ]
}

GET /projects/{id}

Retourne les métadonnées complètes d'un projet. {id} peut être l'identifiant court ou le slug.

GET https://api.eclipse.gg/api/v1/projects/{id}
cURL
curl "https://api.eclipse.gg/api/v1/projects/sodium"
JSON — Réponse
{
  "id":             "AANobbMI",
  "slug":           "sodium",
  "title":          "Sodium",
  "description":    "Modern rendering engine for Minecraft",
  "body":           "<!-- Markdown HTML -->",
  "kind":           "mod",
  "loaders":        ["fabric", "quilt"],
  "mc_versions":    ["1.21.1", "1.20.4"],
  "env": {
    "client": "required",
    "server": "unsupported"
  },
  "categories":     ["performance"],
  "license":        "LicenseRef-LGPL3",
  "color":          7929856,
  "gallery_count":  4,
  "latest_version": "mc1.21.1-0.6.0",
  "downloads":      42800000,
  "follows":        18340,
  "icon_url":       "https://cdn.eclipse.gg/icons/AANobbMI.png",
  "gallery":        ["https://cdn.eclipse.gg/gallery/AANobbMI/01.webp"],
  "team":           [{ "user_id": "u_jellysquid", "role": "Owner" }],
  "created_at":     "2020-09-17T00:00:00Z",
  "updated_at":     "2024-11-02T18:45:00Z",
  "etag":           "\"a3f1c9d2\""  // passez dans If-None-Match pour 304
}
i Supportez If-None-Match / ETag pour éviter le retéléchargement de métadonnées inchangées. En cas d'ETag identique, le serveur retourne 304 Not Modified sans corps.

GET /projects/{id}/versions

Liste paginée des versions d'un projet, de la plus récente à la plus ancienne.

GET https://api.eclipse.gg/api/v1/projects/{id}/versions
ParamètreTypeDescription
mcstringoptionnelFiltre sur la version Minecraft
loaderenumoptionnelFiltre sur le loader
limitintegeroptionnel1–100, défaut 20
cursorstringoptionnelCurseur opaque de pagination
JSON — Item version
{
  "id":           "IIJJKKLL",
  "project_id":   "AANobbMI",
  "version_number": "mc1.21.1-0.6.0",
  "name":          "Sodium 0.6.0 for MC 1.21.1",
  "loaders":       ["fabric"],
  "mc_versions":   ["1.21.1"],
  "channel":       "release",  // release | beta | alpha
  "files": [
    {
      "filename":   "sodium-fabric-0.6.0+mc1.21.1.jar",
      "url":        "https://cdn.eclipse.gg/files/IIJJKKLL/sodium-fabric-0.6.0+mc1.21.1.jar",
      "size":       892416,         // en octets
      "sha256":     "a3f1c9d2e4b8f0...", // hex minuscule, 64 chars
      "primary":    true
    }
  ],
  "dependencies": [
    { "project_id": "P7dR8mSH", "dependency_type": "required" }
  ],
  "downloads":     3200000,
  "changelog":     "Performance improvements...",
  "published_at":  "2024-11-02T18:45:00Z"
}

POST /versions/batch

Récupère les métadonnées de plusieurs versions en une seule requête (max 100 IDs).

POST https://api.eclipse.gg/api/v1/versions/batch
JSON — Corps
{ "ids": ["IIJJKKLL", "MMNNOOPP"] }

La réponse est un tableau d'objets version (même structure que /projects/{id}/versions). Les IDs inconnus sont silencieusement omis.

POST /versions/lookup

Cherche la meilleure version disponible pour un projet donné selon des contraintes loader/mc.

POST https://api.eclipse.gg/api/v1/versions/lookup
JSON — Corps
{
  "project_id": "AANobbMI",
  "loader":     "fabric",
  "mc":         "1.21.1",
  "channel":    "release"   // optionnel, défaut "release"
}

Retourne un unique objet version ou 404 NOT_FOUND si aucune version compatible n'existe.

POST /resolve

Résout récursivement l'arbre de dépendances d'une liste de projets et retourne le plan d'installation complet. Utilisé par le launcher pour installer un modpack ou une liste de mods.

POST https://api.eclipse.gg/api/v1/resolve
JSON — Corps
{
  "projects": [
    { "project_id": "AANobbMI", "version_id": "IIJJKKLL" },
    { "project_id": "P7dR8mSH" }  // version_id optionnel → latest stable
  ],
  "loader":   "fabric",
  "mc":       "1.21.1"
}
JSON — Réponse
{
  "plan": [
    {
      "project_id":  "AANobbMI",
      "version_id":  "IIJJKKLL",
      "filename":    "sodium-fabric-0.6.0+mc1.21.1.jar",
      "url":         "https://cdn.eclipse.gg/files/IIJJKKLL/...",
      "size":        892416,
      "sha256":      "a3f1c9d2e4b8f0...",
      "reason":      "explicit"  // explicit | dependency
    }
  ],
  "conflicts": [],    // versions incompatibles détectées
  "warnings":  []     // dépendances optionnelles non résolues
}

GET /packs

Liste les modpacks publics. Retourne le format de pagination curseur standard avec des items de kind: "modpack".

GET https://api.eclipse.gg/api/v1/packs

Paramètres identiques à /search (sauf kind, forcé à modpack).

POST /packs/import

Importe un fichier .eclps ou une URL de modpack externe. Requiert une authentification.

POST https://api.eclipse.gg/api/v1/packs/import
JSON — Corps
{
  "url": "https://exemple.gg/mon-pack.eclps"  // URL publique du .eclps
}

Retourne un objet projet kind: "modpack" complet avec son id attribué.


GET /skins

Liste les skins publics avec pagination curseur. Items de kind: "skin".

GET https://api.eclipse.gg/api/v1/skins
ParamètreTypeDescription
qstringoptionnelRecherche plein texte
modelenumoptionnelclassic | slim
sortenumoptionnelrelevance | follows | updated
limitintegeroptionnel1–100, défaut 20
cursorstringoptionnelCurseur opaque

POST /skins/upload

Upload un nouveau skin. Corps multipart/form-data. Requiert une authentification.

POST https://api.eclipse.gg/api/v1/skins/upload
Champ formTypeDescription
fileFilerequisPNG 64×64 (classic) ou 64×64 slim, < 256 KB
namestringrequisNom du skin, max 64 caractères
modelenumrequisclassic | slim
publicbooleanoptionnelVisible publiquement, défaut true

GET /accounts/me

Retourne le profil de l'utilisateur authentifié. Requiert Bearer token.

GET https://api.eclipse.gg/api/v1/accounts/me
JSON — Réponse
{
  "id":          "u_a1b2c3",
  "username":    "PlayerOne",
  "email":       "player@exemple.gg",
  "avatar_url":  "https://cdn.eclipse.gg/avatars/u_a1b2c3.png",
  "role":        "creator",   // user | creator | admin
  "created_at":  "2023-01-15T12:00:00Z"
}

POST /accounts/token

Génère un nouveau Personal Access Token (PAT). Nécessite une session active (cookie de session).

POST https://api.eclipse.gg/api/v1/accounts/token
JSON — Corps
{
  "name":       "Mon script d'automatisation",
  "expires_in": 7776000  // secondes, max 90 jours
}
JSON — Réponse (token visible une seule fois)
{
  "token":      "eclp_pat_...",  // valeur secrète, stockez-la de manière sécurisée
  "expires_at": "2025-03-15T12:00:00Z"
}

WS /ws — Temps réel

Connexion WebSocket pour les événements temps réel du launcher (installation, progression, notifications). Nécessite un Bearer token passé en paramètre de requête.

WS wss://api.eclipse.gg/api/v1/ws?token=<pat>

Messages entrants (serveur → client)

JSON — Événement install_progress
{
  "event":    "install_progress",
  "job_id":   "job_abc123",
  "percent":  42,
  "current":  "sodium-fabric-0.6.0.jar",
  "total":    18
}
JSON — Événement install_done
{
  "event":   "install_done",
  "job_id":  "job_abc123",
  "status":  "success"  // success | error
}

Format .eclps

Le fichier .eclps est une archive ZIP standard contenant la définition complète d'un modpack Eclipse.

Structure de l'archive

Arborescence ZIP
mon-pack.eclps/
  manifest.json    # requis — métadonnées et liste des mods
  icon.png         # optionnel — PNG 128×128 ou 256×256
  signature.sig    # optionnel — signature Ed25519 du manifest
  overrides/       # optionnel — fichiers copiés tels quels
    config/
      sodium-options.json
    resourcepacks/
      custom.zip

manifest.json annoté

JSON
{
  // Version du format de manifeste (actuellement 1)
  "format_version": 1,

  // Identifiants du modpack
  "id":          "com.exemple.monpack",   // reverse-domain unique
  "slug":        "mon-pack",
  "name":        "Mon Pack Incroyable",
  "version":     "2.1.0",                  // semver recommandé
  "description": "Un modpack optimisé pour le survie",

  // Cible Minecraft
  "minecraft": {
    "version": "1.21.1",
    "loader":  "fabric",    // fabric | forge | neoforge | quilt
    "loader_version": "0.16.5"
  },

  // Liste des mods à télécharger
  "dependencies": [
    {
      "project_id": "AANobbMI",      // ID Eclipse du projet
      "version_id": "IIJJKKLL",      // ID version exact (ou omis = latest)
      "filename":   "sodium-fabric-0.6.0+mc1.21.1.jar",
      "url":        "https://cdn.eclipse.gg/files/IIJJKKLL/...",
      "size":       892416,            // octets
      "sha256":     "a3f1c9d2e4b8f0...", // hex minuscule 64 chars
      "env": {
        "client": "required",
        "server": "unsupported"
      }
    }
  ],

  // Auteur (optionnel)
  "author": "NomCreateur",

  // Date de création (ISO 8601 Z)
  "created_at": "2024-10-01T09:00:00Z"
}
i Le dossier overrides/ est copié tel quel dans le répertoire d'instance Minecraft après installation des mods. Les fichiers de configuration, resource packs et shaders y ont leur place naturelle.
! Le sha256 est obligatoire pour chaque fichier afin de garantir l'intégrité lors de l'installation. Format : hex minuscule, 64 caractères (ex. a3f1c9d2...). Tout autre casse est rejeté.

Checksums

Tous les fichiers distribués par l'API incluent un checksum SHA-256 pour vérification d'intégrité :

  • Format : hexadécimal minuscule, exactement 64 caractères
  • Algorithme : SHA-256 (RFC 6234)
  • Champ JSON : "sha256"
  • Toute autre casse ou longueur doit être rejetée par le client
Bash — Vérification
sha256sum sodium-fabric-0.6.0+mc1.21.1.jar
# a3f1c9d2e4b8f0...  sodium-fabric-0.6.0+mc1.21.1.jar

Dates ISO 8601

Toutes les dates dans l'API sont en UTC, au format ISO 8601 avec suffixe Z :

Exemples
"2024-06-15T14:23:00Z"    // valide
"2024-06-15T14:23:00.000Z" // valide (millisecondes optionnelles)
"2024-06-15T16:23:00+02:00" // REJETE — toujours UTC

Pour parser en JavaScript : new Date("2024-06-15T14:23:00Z") — nativement supporté par tous les moteurs modernes.