firefrost-operations-manual/docs/tools/curseforge-api-integration.md

CurseForge API Integration

Created: April 2, 2026
Purpose: Modpack version checker and dependency management
Status: Documentation captured, ready for testing

---

🔑 API Credentials

API Key: f865f951-b937-482d-860b-e950bd02bbd2

Authentication Methods:

1. Header: X-Api-Token: f865f951-b937-482d-860b-e950bd02bbd2
2. Query param: ?token=f865f951-b937-482d-860b-e950bd02bbd2

Base URL: https://minecraft.curseforge.com/api

---

📚 Official Documentation

Primary Resource: https://support.curseforge.com/support/solutions/articles/9000197321-curseforge-api

Key Endpoints:

• /api/game/versions - Get list of Minecraft versions
• /api/game/dependencies - Get mod dependencies
• /api/projects/{projectId}/upload-file - Upload new file
• /api/projects/{projectId}/update-file - Update existing file

---

🎯 Use Case: Modpack Version Checker

Goal: Automatically check if modpack versions are up to date

Workflow:

1. Query CurseForge for latest game versions
2. Compare against installed modpack versions
3. Alert if updates available
4. Optionally auto-update (future feature)

---

📋 Game Versions API

Endpoint: GET /api/game/versions

Example Response:

[
  {
    "id": 158,
    "gameVersionTypeID": 42,
    "name": "1.8.4",
    "slug": "1-8-4"
  }
]

Use Case:

• Get list of all Minecraft versions
• Filter for specific version ranges
• Check compatibility

---

🔧 Game Dependencies API

Endpoint: GET /api/game/dependencies

Example Response:

[
  {
    "id": 42,
    "name": "Bukkit",
    "slug": "bukkit"
  }
]

Use Case:

• Identify mod loader requirements (Forge, Fabric, Bukkit)
• Verify dependency compatibility

---

📦 Project File Management

Upload New File

Endpoint: POST /api/projects/{projectId}/upload-file

Content-Type: multipart/form-data

Fields:

• metadata (JSON)
• file (actual file)

Metadata Schema:

{
  "changelog": "Version updates and bug fixes",
  "changelogType": "markdown",
  "displayName": "My Modpack v1.2.3",
  "gameVersions": [157, 158],
  "releaseType": "release",
  "relations": {
    "projects": [
      {
        "slug": "jei",
        "type": "requiredDependency"
      }
    ]
  }
}

Response:

{
  "id": 20402
}

---

💡 Implementation Ideas

Version Checker Script

#!/bin/bash
# Check CurseForge for latest Minecraft versions

API_KEY="f865f951-b937-482d-860b-e950bd02bbd2"
ENDPOINT="https://minecraft.curseforge.com/api/game/versions"

curl -H "X-Api-Token: $API_KEY" "$ENDPOINT"

Python Version Checker

import requests

API_KEY = "f865f951-b937-482d-860b-e950bd02bbd2"
BASE_URL = "https://minecraft.curseforge.com/api"

def get_game_versions():
    headers = {"X-Api-Token": API_KEY}
    response = requests.get(f"{BASE_URL}/game/versions", headers=headers)
    return response.json()

def check_modpack_version(target_version):
    versions = get_game_versions()
    # Filter and compare logic here
    pass

---

🚀 Next Steps (POST-LAUNCH)

Phase 1: Manual Testing

• Test API authentication
• Retrieve game versions list
• Identify our modpack version IDs
• Document version mapping

Phase 2: Version Checker

• Build script to query latest versions
• Compare against installed versions
• Generate update report
• Alert Trinity via Discord webhook

Phase 3: Automation

• Schedule periodic checks (daily/weekly)
• Store version history in PostgreSQL
• Build Trinity Console module
• Add update notifications to dashboard

Phase 4: Advanced Features

• Auto-update workflow (with approval)
• Dependency conflict detection
• Rollback capability
• Version change tracking in audit log

---

📝 Notes

• Security: API key has full project access - protect it
• Rate Limits: Unknown - test conservatively
• Maven Support: Available for dependency management
• Project ID: Found in CurseForge project URL

---

🔗 Related Resources

• CurseForge Project: (TBD - add modpack project URL)
• Maven Endpoint: https://minecraft.curseforge.com/api/maven/
• API Token Management: https://authors-old.curseforge.com/account/api-tokens

---

Status: Ready for testing after soft launch (April 16+)
Priority: Medium (operational improvement, not launch blocker)
Owner: The Wizard

Fire + Frost + Foundation = Where Love Builds Legacy 🔥❄️