canonical: https://jentic.com/apis/curseforge.com/curseforge

# CurseForge API

CurseForge is a long-running distribution platform for game mods and addons, particularly for Minecraft, World of Warcraft, and other titles. The API provides programmatic access to the catalogue of games, mods, files, categories, and Minecraft-specific resources, with endpoints for searching mods, fetching mod files and changelogs, fingerprint matching for installed addons, and resolving Minecraft versions and mod loaders. Authentication is by an x-api-key header.

## For AI agents

Search game mods, retrieve mod files and changelogs, match installed addons by fingerprint, and resolve Minecraft versions and mod loaders.

## Scope

Does not handle game purchases, account management, or mod uploading - use for searching, identifying, and downloading mods only.

## Capabilities

- Search mods across supported games with category, version, and sort filters
- Retrieve mod metadata, descriptions, and changelogs for a specific mod or version
- Resolve download URLs for mod files attached to a mod
- Match installed addon files to known mods using fingerprint and fuzzy fingerprint endpoints
- Enumerate Minecraft versions and supported mod loaders for compatibility checks
- List supported games and category trees for catalogue navigation

## Use cases

### Mod Manager and Launcher Integration

Power a third-party Minecraft launcher or mod manager that lets users browse, install, and update mods from CurseForge. Use `/v1/mods/search` for discovery, `/v1/mods/{modId}/files` for version listings, and `/v1/mods/{modId}/files/{fileId}/download-url` to retrieve the download URL for the actual jar. Suitable for desktop launchers, container builders, and modpack assemblers.

Example prompt: Call GET `/v1/mods/search` with gameId for Minecraft and searchFilter='create', then GET `/v1/mods/{modId}/files` to list available versions, then GET `/v1/mods/{modId}/files/{fileId}/download-url` to fetch the jar

### Installed Mod Identification

Identify a folder of unknown mod jars by computing the CurseForge fingerprint of each file and submitting them to `/v1/fingerprints.` The endpoint returns matched mod and file IDs so a tool can resolve names, versions, and update paths. Useful for migration tools, sync utilities, and modpack diff viewers.

Example prompt: Compute fingerprints for files in a mods folder, then POST `/v1/fingerprints` with the fingerprint list to resolve them to known CurseForge mod IDs

### Modpack Build and Compatibility Check

Build a modpack manifest and verify each mod is compatible with a target Minecraft version and mod loader. Combine `/v1/games/{gameId}/versions` for the version catalogue, `/v1/minecraft/modloader` for loader options, and `/v1/mods/{modId}/files` for per-mod file metadata to assemble a coherent pack.

Example prompt: Call GET `/v1/minecraft/version` to list versions, then for each candidate mod call GET `/v1/mods/{modId}/files` and filter by gameVersion=1.20.4 and modLoaderType=1 for Forge

### Mod Discovery Page

Render a discovery page that surfaces featured and trending mods alongside category browsing. Use POST `/v1/mods/featured` for curated lists and GET `/v1/categories` for navigation, then deep-link into mod detail pages with `/v1/mods/{modId}` and `/v1/mods/{modId}/description.`

Example prompt: Call POST `/v1/mods/featured` with gameId for Minecraft to fetch popular and recently updated mods for a homepage carousel

### AI Agent Mod Lookup via Jentic

An AI agent helping a user find or update Minecraft mods uses Jentic to call CurseForge directly. The agent searches for 'search mods', loads `/v1/mods/search`, supplies a gameId and search filter, and returns the matching mod list to the user without manual integration work.

Example prompt: Use Jentic to search 'search mods' and execute `/v1/mods/search` with gameId for Minecraft and searchFilter='shader' to recommend shader mods

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/mods/search` | Search mods with filters |
| GET | `/v1/mods/{modId}` | Get mod details |
| GET | `/v1/mods/{modId}/files` | List files for a mod |
| GET | `/v1/mods/{modId}/files/{fileId}/download-url` | Get a mod file download URL |
| POST | `/v1/fingerprints` | Match files to mods by fingerprint |
| POST | `/v1/mods/featured` | Get featured and popular mods |
| GET | `/v1/minecraft/version` | List Minecraft versions |
| GET | `/v1/minecraft/modloader` | List Minecraft mod loaders |

## Key resources

- **Mods** — Search, list, and retrieve mod metadata, descriptions, and featured collections
- **Files** — List mod files, fetch changelogs, and resolve download URLs
- **Fingerprints** — Match installed jar files to known mods via exact and fuzzy fingerprint lookup
- **Games** — List supported games and their version catalogues
- **Minecraft** — Minecraft-specific version and mod loader resources
- **Categories** — Browse the category tree used to organise mods

## Why Jentic

- **Setup:** Wiring CurseForge by hand means provisioning an x-api-key, setting the x-api-key header on every request, and handling its mod, file, and fingerprint call shapes yourself. Through Jentic you install once, import the CurseForge API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** CurseForge puts the mod id in the URL path (`/v1/mods/{modId}/files/...`), so a rule can pin your agent to one mod: it can read that mod's details and files and nothing else. You choose the operations it may call, so a corpus-wide lookup such as the featured-mods call is not included unless you add it.
- **Credential handling:** Your CurseForge x-api-key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'search mods' or 'get a mod download URL', and Jentic returns the matching CurseForge operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Modrinth API** — Direct alternative for Minecraft mod search and download
- **Twitch API** — Game streaming platform commonly used alongside mod platforms for community content

## FAQ

### Does CurseForge publish an official OpenAPI specification?

Yes. CurseForge serves one from its own API host at https://api.curseforge.com/swagger/v1/swagger.json, titled CurseForge Core API, and that document is canonical. The specification behind this page is a curated Jentic variant of the same API: 22 operations covering the public catalogue of games, mods, files, fingerprints, categories and Minecraft resources, validated and kept agent-ready. The official document is wider at 46 operations, including v2 and v3 search paths and user subscription calls, and one path differs: the POST `/v1/files` call in our spec is published there under `/v1/mods/files` instead. Read the official document when you need the full surface.

### What authentication does the CurseForge API use?

The API uses an API key sent in the x-api-key request header. Through Jentic the key is held in the encrypted vault and injected at execution time, so the raw key never enters the agent's prompt.

### Can I download mod files with the CurseForge API?

Yes. Call GET `/v1/mods/{modId}/files/{fileId}/download-url` to obtain the download URL for the file, then issue a standard HTTP GET to that URL to fetch the jar.

### What are the rate limits for the CurseForge API?

CurseForge does not document a request rate limit, and neither its own document nor the spec behind this page declares one, so treat throttling as undefined rather than absent. The limits its documentation does publish are on paging: the maximum page size is 50 results per page, capped at 10,000 total results, with index plus pageSize required to stay within 10,000.

### Is there a CurseForge MCP server?

You don't need an MCP server to give your agent CurseForge. Jentic connects it directly from the API Directory: import CurseForge, store your x-api-key once, and your agent can search mods, list a mod's files, and resolve download URLs, with no extra tool definitions loaded into its context.

### How do I identify mods already installed in a folder?

Compute the CurseForge fingerprint for each jar file, then POST `/v1/fingerprints` with the fingerprint list. The response returns exactMatches and partialMatches, each carrying the matched mod id and the file record, and POST `/v1/fingerprints/fuzzy` is available for near matches by folder.

### How do I list supported Minecraft versions through Jentic?

Install Jentic One on its own machine, run `jentic register` on the machine your agent runs on, then import the CurseForge API from the API Directory and store your x-api-key once. Your agent searches by intent for 'list minecraft versions', loads the schema for GET `/v1/minecraft/version`, and executes it. The response is the version catalogue you can pass as the gameVersion query filter on GET `/v1/mods/{modId}/files.`

### Can I limit what my agent is allowed to do with the CurseForge API?

Yes. Because you run Jentic One yourself, your own rules decide which CurseForge operations and credentials the agent may use. CurseForge puts the mod id in the URL path (`/v1/mods/{modId}/files/...`), so you can pin the agent to a single mod and let it read only that mod's details and files. You also choose the operations it may call, so a corpus-wide lookup like POST `/v1/mods/featured` stays out of reach unless you explicitly add it. Every one of the 22 operations in this spec reads data; none of them writes to CurseForge.