canonical: https://jentic.com/apis/api.modrinth.com/modrinth

# Modrinth API

Jentic publishes the only available OpenAPI specification for Modrinth API, keeping it validated and agent-ready. Modrinth is an open mod hosting platform for Minecraft mods, modpacks, resource packs, and shaders, served by the Labrinth backend. The API exposes 26 endpoints covering project search, project and version CRUD, multi-id batch fetches, version-by-file-hash lookups, user profile management, project team membership, tag taxonomies, and instance statistics. It is a strong fit for mod launchers, automated update checkers, and any tool building a Minecraft modding pipeline.

## For AI agents

Search, publish, and manage Minecraft mods on Modrinth: search projects, create and modify projects and versions, look up versions by file hash, manage user profiles, and read tag taxonomies.

## Scope

Does not handle in-game Minecraft state, server administration, or user payments - use for Modrinth project, version, and user metadata only.

## Capabilities

- Search Modrinth projects by query, facets, and filters with pagination
- Create new projects and modify or delete existing projects on behalf of an authenticated user
- List, create, modify, and delete versions for a project including dependency declarations
- Look up the version that owns a specific file via SHA-1 or SHA-512 hash for update detection
- Fetch multiple projects or versions in a single batched call by ID
- Read user profiles, list a user's projects, and update profile details for the authenticated user
- List taxonomy tags (categories, mod loaders, game versions, licenses, donation platforms) used to classify projects

## Use cases

### Mod Launcher Update Checker

Build a Minecraft launcher that detects which installed mods have new versions on Modrinth by hashing each local jar and calling `/version_file/{hash}.` The launcher then offers users one-click updates. Most launchers ship a working hash-based updater in 2 to 3 days using the public read API.

Example prompt: Compute the SHA-512 of every jar in the user's mods folder, call `/version_file/{hash}` for each, and present any version where versionId is newer than the locally installed one.

### Automated Mod Publishing

Wire Modrinth into a CI pipeline so that every tagged release on GitHub publishes a new version to Modrinth via POST /version. The job uploads the jar, sets dependency constraints, and updates the project description if the changelog has changed. Typical setup is a day to script the release.

Example prompt: After a successful GitHub release for project 'tinkers-auto-smelt', call POST /version with the jar attached, version_number from the release tag, and game_versions ['1.21'].

### Modpack Curation Dashboard

A modpack curator can use /search and /projects to browse and batch-fetch project metadata, then surface a curated list to their community. The /tag endpoints supply the categories and loader filters that drive faceted UI. Most teams build the dashboard in a week.

Example prompt: Call /search with facets ['categories:adventure', 'project_type:modpack', 'versions:1.21'] and present the top 50 results sorted by downloads.

### AI Modding Assistant

An AI assistant for Minecraft modders can answer 'find me a shader pack that works with Iris on 1.20.4' or 'publish the new version of my mod' through Jentic. Modrinth bearer tokens stay in your Jentic One instance and never enter agent context. Setup is under an hour.

Example prompt: Use Jentic to search for 'search Modrinth projects', execute /search with the user's natural-language query parsed into facets, and present the top 10 matches.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/search` | Search Modrinth projects |
| GET | `/project/{idOrSlug}` | Get a project by ID or slug |
| POST | `/project` | Create a new project |
| POST | `/version` | Create a new version of a project |
| GET | `/version_file/{hash}` | Get a version from a file hash |
| GET | `/user` | Get the authenticated user |
| GET | `/tag/category` | List all categories |

## Key resources

- **Projects** — Search, create, modify, batch-fetch, and delete projects (mods, modpacks, resource packs, shaders)
- **Versions** — List, create, modify, batch-fetch, and delete versions of a project
- **Version Files** — Look up the version that owns a specific jar by SHA-1 or SHA-512 hash
- **Users** — Read and modify user profiles and list a user's projects
- **Project Team** — List the team members of a project
- **Tags** — List categories, loaders, game versions, licenses, and donation platforms
- **Statistics** — Read aggregate Modrinth instance statistics

## Why Jentic

- **Setup:** Wiring the Modrinth API by hand means setting up its bearer token auth and coding your own calls to the search, project, and version endpoints. Through Jentic you install once, import the Modrinth API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Modrinth puts the project id or slug and file hash in the URL path (`/project/{idOrSlug}`, `/version_file/{hash}`), and those lookups are read-only, so a rule can pin your agent to reading one project. You choose the operations it may call, so creating a project or version is not included unless you add it.
- **Credential handling:** Your Modrinth token 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 for a mod' or 'get project metadata by slug', and Jentic returns the matching Modrinth operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **CurseForge API** — Mod hosting platform owned by Overwolf, dominant in Minecraft modding
- **Hypixel API** — Player and game data from the Hypixel Minecraft server network
- **GitHub API** — Source-control platform that hosts most Modrinth mod source code

## FAQ

### Why is there no official OpenAPI spec for Modrinth API?

Modrinth (Labrinth) does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Modrinth API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Modrinth API use?

Modrinth uses HTTP token authentication under the tokenAuth bearer scheme. Generate a personal access token from your Modrinth profile and pass it as a bearer token. Through Jentic, the token is stored encrypted in your Jentic One instance and the agent receives only a scoped session at execution time.

### Can I look up a Modrinth version by file hash?

Yes. GET `/version_file/{hash}` resolves a SHA-1 or SHA-512 hash to the version that owns the file. This is the standard way for mod launchers to detect installed mods and check for available updates.

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

Modrinth applies a 300 requests per minute rate limit on its public API. Authenticated requests share that pool; if you exceed it, the API returns 429 with a Retry-After header. Cache aggressively when paginating large result sets.

### How do I publish a new mod version with the Modrinth API through Jentic?

Run pip install jentic, then search for 'create a new mod version'. Jentic returns the POST /version operation schema. Execute it with the project_id, version_number, game_versions, loader, and primary file payload, then verify with GET `/version/{id}.`

### Does the Modrinth API support project search with facets?

Yes. GET /search accepts the query parameter for free text plus facets for project_type, categories, versions, loaders, and license. This is the same engine that powers the modrinth.com search experience.

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

Yes. Because you self-host Jentic One, your own rules decide which Modrinth operations and credentials the agent may use. You can pin it to read-only lookups like GET `/project/{idOrSlug}` and GET `/version_file/{hash}`, since Modrinth takes the project id, slug, or file hash in the URL path, so a rule can scope the agent to reading a single project. Write operations such as POST /project or POST /version are not available to the agent unless you explicitly add them.