# CurseForge API Integration

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

---

## 🔑 API Credentials

**Primary API Key (General Use):**
```
f865f951-b937-482d-860b-e950bd02bbd2
```
- Application: Firefrost Gaming CurseForge Integration
- Status: Approved

**Modpack Version Checker API Key:**
```
$2a$10$OVK9ml7bEJdcfTJhBSuK1O5AFz2qq3mwpb35RTTwVfmdvzQFOA7M
```
- Application: Firefrost Modpack Version Checker (3rd Party API)
- Status: Approved April 2, 2026
- Email confirmation: Received 8:22 AM
- Use case: Automated modpack version checking for server updates

**Authentication Methods:**
1. Header: `X-Api-Token: [API_KEY]`
2. Query param: `?token=[API_KEY]`

**Recommendation:** Use the Modpack Version Checker key for automated version checking scripts to keep usage separated by purpose.

**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:**
```json
[
  {
    "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:**
```json
[
  {
    "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:**
```json
{
  "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:**
```json
{
  "id": 20402
}
```

---

## 💡 Implementation Ideas

### Version Checker Script

```bash
#!/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

```python
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** 🔥❄️