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 :
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.
Authentification
Passez votre token dans l'en-tête Authorization :
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ête | Type | Description |
|---|---|---|
| X-RateLimit-Limit | integer | Quota maximal par fenêtre (ex. 300) |
| X-RateLimit-Remaining | integer | Requêtes restantes dans la fenêtre courante |
| X-RateLimit-Reset | unix ts | Timestamp UNIX de réinitialisation du compteur |
| Retry-After | seconds | Pré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.
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 :
{
"error": {
"code": "NOT_FOUND", // code machine, snake_case majuscule
"message": "Project not found" // message humain en anglais
}
}
| HTTP | code | Signification |
|---|---|---|
| 400 | BAD_REQUEST | Paramètre manquant ou invalide |
| 401 | UNAUTHORIZED | Token absent ou expiré |
| 403 | FORBIDDEN | Token valide mais permissions insuffisantes |
| 404 | NOT_FOUND | Ressource inexistante |
| 409 | CONFLICT | Doublon (slug déjà pris, version existante…) |
| 422 | UNPROCESSABLE | Corps JSON syntaxiquement valide mais sémantiquement rejeté |
| 429 | RATE_LIMITED | Quota dépassé |
| 500 | INTERNAL_ERROR | Erreur serveur interne |
Pagination curseur
L'API utilise une pagination par curseur opaque (pas d'offset). Le corps de réponse d'une liste inclut :
{
"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.
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
Recherche paginée de projets (mods, modpacks, skins, resource packs). Retourne un objet de pagination curseur.
Paramètres de requête
| Paramètre | Type | Description | |
|---|---|---|---|
| q | string | optionnel | Terme de recherche plein texte |
| kind | enum | optionnel | mod | modpack | skin | resourcepack |
| mc | string | optionnel | Version Minecraft cible (ex. 1.21.1) |
| loader | enum | optionnel | fabric | forge | neoforge | quilt |
| categories | string | optionnel | Catégories séparées par des virgules (ex. combat,utility) |
| env | enum | optionnel | client | server | both |
| license | string | optionnel | Identifiant SPDX (ex. MIT, LicenseRef-Eclipse) |
| sort | enum | optionnel | relevance (défaut) | downloads | follows | updated | created |
| limit | integer | optionnel | Résultats par page, 1–100, défaut 20 |
| cursor | string | optionnel | Curseur opaque retourné par la réponse précédente |
Exemple de requête
curl -G "https://api.eclipse.gg/api/v1/search" \ --data-urlencode "q=sodium" \ --data-urlencode "kind=mod" \ --data-urlencode "loader=fabric" \ --data-urlencode "mc=1.21.1" \ --data-urlencode "sort=downloads" \ --data-urlencode "limit=20"
Exemple de réponse
{
"items": [
{
"id": "AANobbMI",
"slug": "sodium",
"title": "Sodium",
"description": "Modern rendering engine for Minecraft",
"kind": "mod", // enum: mod | modpack | skin | resourcepack
"loaders": ["fabric", "quilt"],
"mc_versions": ["1.21.1", "1.20.4"],
"env": {
"client": "required", // required | optional | unsupported
"server": "unsupported"
},
"categories": ["performance", "optimization"],
"downloads": 42800000,
"follows": 18340,
"color": 7929856, // couleur dominante en decimal ARGB
"gallery_count": 4,
"latest_version": "mc1.21.1-0.6.0",
"icon_url": "https://cdn.eclipse.gg/icons/AANobbMI.png",
"license": "LicenseRef-LGPL3",
"updated_at": "2024-11-02T18:45:00Z" // ISO 8601 Z
}
],
"next_cursor": "eyJpZCI6IkFBTm9iYk1JIn0",
"total_estimate": 312
}
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.
| Paramètre | Type | Description | |
|---|---|---|---|
| q | string | requis | Préfixe à compléter (min 2 caractères) |
| kind | enum | optionnel | Filtre sur le type de projet |
| limit | integer | optionnel | 1–8, défaut 5 |
{
"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.
curl "https://api.eclipse.gg/api/v1/projects/sodium"
{
"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
}
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.
| Paramètre | Type | Description | |
|---|---|---|---|
| mc | string | optionnel | Filtre sur la version Minecraft |
| loader | enum | optionnel | Filtre sur le loader |
| limit | integer | optionnel | 1–100, défaut 20 |
| cursor | string | optionnel | Curseur opaque de pagination |
{
"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).
{ "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.
{
"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.
{
"projects": [
{ "project_id": "AANobbMI", "version_id": "IIJJKKLL" },
{ "project_id": "P7dR8mSH" } // version_id optionnel → latest stable
],
"loader": "fabric",
"mc": "1.21.1"
}
{
"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".
Paramètres identiques à /search (sauf kind, forcé à modpack).
POST /packs/import
Importe un fichier .eclps ou une URL de modpack externe. Requiert une authentification.
{
"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".
| Paramètre | Type | Description | |
|---|---|---|---|
| q | string | optionnel | Recherche plein texte |
| model | enum | optionnel | classic | slim |
| sort | enum | optionnel | relevance | follows | updated |
| limit | integer | optionnel | 1–100, défaut 20 |
| cursor | string | optionnel | Curseur opaque |
POST /skins/upload
Upload un nouveau skin. Corps multipart/form-data. Requiert une authentification.
| Champ form | Type | Description | |
|---|---|---|---|
| file | File | requis | PNG 64×64 (classic) ou 64×64 slim, < 256 KB |
| name | string | requis | Nom du skin, max 64 caractères |
| model | enum | requis | classic | slim |
| public | boolean | optionnel | Visible publiquement, défaut true |
GET /accounts/me
Retourne le profil de l'utilisateur authentifié. Requiert Bearer token.
{
"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).
{
"name": "Mon script d'automatisation",
"expires_in": 7776000 // secondes, max 90 jours
}
{
"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.
Messages entrants (serveur → client)
{
"event": "install_progress",
"job_id": "job_abc123",
"percent": 42,
"current": "sodium-fabric-0.6.0.jar",
"total": 18
}
{
"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
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é
{
// 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"
}
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.
a3f1c9d2...). Tout autre casse est rejeté.
Deep links
Le protocole eclipse:// permet d'invoquer directement le client depuis un navigateur ou une autre application.
| URI | Action |
|---|---|
| eclipse://install?type=mod&slug={slug}&version={version_id} | Installe un mod dans l'instance active |
| eclipse://install?type=resourcepack&slug={slug}&version={version_id} | Installe un resource pack |
| eclipse://modpack/install?url={url_eclps} | Installe un modpack depuis une URL .eclps |
| eclipse://skin/apply?id={skin_id} | Applique un skin Eclipse existant |
| eclipse://skin/apply?url={skin_url}&model={classic|slim} | Applique un skin depuis une URL PNG externe |
| eclipse://open?page=mods | Ouvre la page Mods dans le launcher |
| eclipse://open?page=modpacks | Ouvre la page Modpacks |
| eclipse://open?page=skins | Ouvre la page Skins |
| eclipse://open?page=dashboard | Ouvre le tableau de bord |
encodeURIComponent() en JavaScript). Le launcher doit être installé sur la machine de l'utilisateur pour que le protocole soit géré.
Exemple de bouton HTML
<!-- Bouton d'installation directe -->
<a href="eclipse://install?type=mod&slug=sodium&version=IIJJKKLL">
Installer dans Eclipse
</a>
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
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 :
"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.